Generate
File uploads
Models take media as public HTTPS URLs. When the file is on your machine, upload it once and use the URL it gets.
Inputs are URLs
image_urls, image_url, end_image_url, video_url, audio_url and the reference_*_urls fields all take URLs that download without cookies or custom headers and stay valid until the job ends. A signed link from your own storage works if it outlives the job.
Get an upload URL
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://…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"
}
}Upload the bytes
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 upload URL is a secret
Do not send your API key to upload_url, and do not log the URL. It stops taking uploads 15 minutes after you ask for it; ask again if it expires.
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.
Errors
| Status | code | When |
|---|---|---|
| 400 | invalid_request | Missing or invalid content_type or size_bytes. |
| 413 | asset_too_large | size_bytes is over the limit; details.max_bytes says the limit. |
| 409 | asset_upload_incomplete | Completing an upload whose bytes have not arrived. |