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:

InputBest forLimit
A public HTTPS URLFiles that are already onlineSee Public URLs below
data:image/png;base64,…A small file, in the same request10 MiB each, 16 per request, 20 MiB per request
POST /v1/files/uploadA local file up to 100 MiB100 MiB
POST /v1/files/generate-upload-urlA local file of any size2 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
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.

NameTypeRequiredDescription
Content-TypeheaderYesThe file's MIME type: image/png, video/mp4, audio/wav…
filenamequeryNoThe original name, kept with the upload. Or send X-Sume-File-Name.
checksum_sha256queryNoHex SHA-256 of the file. Sume refuses the upload if the bytes do not match. Or send X-Sume-Checksum-Sha256.
Idempotency-KeyheaderNoSend 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
201 Created
{
  "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

NameTypeRequiredDescription
content_typestringYesMIME type: image/png, image/jpeg, video/mp4, audio/wav…
size_bytesintegerYesExact size in bytes, up to 2 GiB. It is signed into the upload URL.
filenamestringNoThe original name, kept with the upload.
cURL
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}'
201 Created
{
  "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.png

The 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.

The upload URLs are secrets

Do not send your API key to either URL, and do not log them. They stop taking uploads 15 minutes after you ask for them; ask again if they expire.

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/upload goes through https://api.sume.com, and from a country where this happens upload_url does 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

StatuscodeWhen
400invalid_requestMissing or invalid content_type or size_bytes.
400invalid_data_uriA data: URI is not base64 image, video or audio. details.field names the field.
400asset_checksum_mismatchThe uploaded bytes do not match checksum_sha256.
413asset_too_largesize_bytes, or the body of POST /v1/files/upload, is over the limit; details.max_bytes says the limit.
413payload_too_largeA JSON body is over 4 MiB, or over 20 MiB with data: URIs.
413data_uri_too_largeA data: URI is over 10 MiB. Upload the file and send its URL.
4xxupload_rejectedMedia storage refused the PUT: the upload URL has expired, or the headers differ from upload_headers. Ask for a new upload URL.
409asset_upload_incompleteCompleting an upload whose bytes have not arrived. details.fallback_upload_url is a fresh URL to send them to.
503asset_storage_unavailableMedia 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.