Generate
File uploads
Models take media as URLs. Pass a public HTTPS URL, a small file inline as a data: URI, or upload the file once and use the URL it gets.
Three ways to pass a file
image_urls, image_url, end_image_url, video_url, audio_url and the reference_*_urls fields each take one of these:
| Input | Best for | Limit |
|---|---|---|
| A public HTTPS URL | Files that are already online | See Public URLs below |
data:image/png;base64,… | A small file, in the same request | 10 MiB each, 16 per request, 20 MiB per request |
POST /v1/files/upload | A local file up to 100 MiB | 100 MiB |
POST /v1/files/generate-upload-url | A local file of any size | 2 GiB |
Public URLs
Sume and the model download the file themselves, so a URL keeps working even when your own network has trouble reaching our storage.
- HTTPS only, at most 2,048 characters, with no user name, password or port in it. It must download without cookies or custom headers.
- Up to 5 redirects. Each hop must be public HTTPS too.
- Images are JPEG, PNG or WebP. On most video models each side must be 300–6000 px, with an aspect ratio between 2:5 and 5:2. A file over the limits is refused at submit with
400. - The URL must stay valid until the job ends: the model downloads it again after the job starts, later still if the job waits in the queue. A signed link from your own storage should last at least one hour.
data: URIs
Put a small file straight into the input field as a base64 data: URI. Sume stores it before the job starts and sends the model a https://media.sume.com/… URL in its place.
curl -X POST https://api.sume.com/v1/video-router/generate \
-H "Authorization: Bearer $SUME_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "seedance-2.5", "prompt": "The cup steams", "image_url": "data:image/png;base64,iVBORw0KGgo…"}'data:<image, video or audio type>;base64,<data>, up to 10 MiB of file each and 16 per request. A request that carries data: URIs may be up to 20 MiB; other requests stay at 4 MiB.- The part before the first comma may be up to 1,024 characters. The base64 may hold whitespace and line breaks; they are removed.
- For bigger files, or the same file in many jobs, upload it once instead and reuse its URL.
Upload in one request
POSThttps://api.sume.com/v1/files/upload
Send the raw bytes as the body, with the file's Content-Type and your API key. Up to 100 MiB. The bytes go through https://api.sume.com, and the answer has the URL to use.
| Name | Type | Required | Description |
|---|---|---|---|
Content-Type | header | Yes | The file's MIME type: image/png, video/mp4, audio/wav… |
filename | query | No | The original name, kept with the upload. Or send X-Sume-File-Name. |
checksum_sha256 | query | No | Hex SHA-256 of the file. Sume refuses the upload if the bytes do not match. Or send X-Sume-Checksum-Sha256. |
Idempotency-Key | header | No | Send the same key on a retry to get the same file back, not a second copy. |
curl -X POST "https://api.sume.com/v1/files/upload?filename=cup.png" \
-H "Authorization: Bearer $SUME_API_KEY" \
-H "Content-Type: image/png" \
--data-binary @cup.png{
"data": {
"public_url": "https://media.sume.com/assets/asset_6f1d0c2b9a8e4f7d/source.png",
"asset_id": "asset_6f1d0c2b9a8e4f7d",
"content_type": "image/png",
"size_bytes": 482113
}
}Upload with a signed URL
For a file of any size up to 2 GiB, ask for a signed URL, then PUT the bytes to it.
POSThttps://api.sume.com/v1/files/generate-upload-url
| Name | Type | Required | Description |
|---|---|---|---|
content_type | string | Yes | MIME type: image/png, image/jpeg, video/mp4, audio/wav… |
size_bytes | integer | Yes | Exact size in bytes, up to 2 GiB. It is signed into the upload URL. |
filename | string | No | The original name, kept with the upload. |
curl -X POST https://api.sume.com/v1/files/generate-upload-url \
-H "Authorization: Bearer $SUME_API_KEY" \
-H "Content-Type: application/json" \
-d '{"content_type": "image/png", "size_bytes": 482113}'{
"data": {
"public_url": "https://media.sume.com/assets/asset_6f1d0c2b9a8e4f7d/source.png",
"upload_url": "https://api.sume.com/v1/storage/…",
"fallback_upload_url": "https://…r2.cloudflarestorage.com/…",
"upload_method": "PUT",
"upload_headers": {
"content-type": "image/png",
"content-length": "482113"
},
"content_type": "image/png",
"expires_at": "2026-10-21T02:46:37.491Z",
"asset_id": "asset_6f1d0c2b9a8e4f7d"
}
}PUT the file to upload_url with exactly the upload_headers. Then pass public_url to a model; it serves the file as soon as the PUT returns 200.
curl -X PUT "$UPLOAD_URL" \
-H "content-type: image/png" \
-H "content-length: 482113" \
--data-binary @cup.pngThe two URLs reach the same place by two routes: one goes straight to media storage, the other through https://api.sume.com. Sume puts first the route most likely to work from where you call. If the PUT to upload_url times out or cannot connect, send the same bytes to fallback_upload_url.
If the upload can't connect
Some internet providers block the addresses our media storage uses. In Spain, for example, providers block shared Cloudflare addresses during LaLiga matches by court order, and a PUT to storage then times out. https://api.sume.com was not blocked.
POST /v1/files/uploadgoes throughhttps://api.sume.com, and from a country where this happensupload_urldoes too, so most uploads are not affected.- On a timeout or a connection error, retry once, then use
fallback_upload_url.@sume-com/sdk, the CLI and the MCP server do this for you. - If no route connects, the network is blocking both. Try again later or from another network, or pass a public HTTPS URL from your own storage instead: Sume downloads it from outside your network.
Check an upload
Optional. POST /v1/assets/{asset_id}/complete confirms the bytes arrived whole before you submit a job, which helps after a flaky connection. If they never arrived, it answers 409 asset_upload_incomplete with a fresh details.fallback_upload_url to send them to.
Errors
| Status | code | When |
|---|---|---|
| 400 | invalid_request | Missing or invalid content_type or size_bytes. |
| 400 | invalid_data_uri | A data: URI is not base64 image, video or audio. details.field names the field. |
| 400 | asset_checksum_mismatch | The uploaded bytes do not match checksum_sha256. |
| 413 | asset_too_large | size_bytes, or the body of POST /v1/files/upload, is over the limit; details.max_bytes says the limit. |
| 413 | payload_too_large | A JSON body is over 4 MiB, or over 20 MiB with data: URIs. |
| 413 | data_uri_too_large | A data: URI is over 10 MiB. Upload the file and send its URL. |
| 4xx | upload_rejected | Media storage refused the PUT: the upload URL has expired, or the headers differ from upload_headers. Ask for a new upload URL. |
| 409 | asset_upload_incomplete | Completing an upload whose bytes have not arrived. details.fallback_upload_url is a fresh URL to send them to. |
| 503 | asset_storage_unavailable | Media storage did not answer, or answered with an error of its own. Nothing about your request is wrong: send the same request again after retry-after, to the same upload URL. |