Reviewed 2026-11-10 · API version 2026-11-09 · Read Markdown
Uploading and retaining media
Media bytes travel directly to temporary private object storage. REST and MCP
return upload instructions; they do not accept binary file content in tool JSON.
Storage must be configured on the deployment or upload creation returns
provider_unavailable.
Upload lifecycle
- Call
POST /api/v1/media/upload-intentswith filename, declared MIME and byte count. Save the returnedassetIdandsessionIdas separate identities. - Inspect
method. Forpresigned_put, upload the whole file touploadUrlusing the returned headers. Formultipart_initiated, split usingpartSizeBytes, upload each numbered part to its returned URL and retain its ETag receipt. Never add the AiVideoEditor bearer key to storage requests. - Finalize at
POST /api/v1/media/{assetId}/finalizewithsessionIdand, for multipart,multipart.partscontaining eachpartNumberandetag. - Use the finalized asset ID in the draft's
mediaIds. An upload intent alone does not make the asset publishable.
The server observes actual bytes and format on an immutable final copy. Declared size/MIME are reservation inputs, not proof of file validity. Supported baseline families are JPEG, PNG and MP4; individual destinations can impose stricter limits. The current maximum file size is 500 MiB (524,288,000 bytes). Files at or above 50 MiB use multipart, normally with 16 MiB parts. Always follow returned sizes, URLs and expiry rather than deriving them from these defaults.
{
"sessionId": "<session UUID from upload-intents>",
"multipart": {
"parts": [
{ "partNumber": 1, "etag": "<ETag returned by storage>" }
]
}
}
This is a multipart shape illustration; include every actual part. Single-PUT
finalization sends only sessionId. Give each new API mutation its own
Idempotency-Key; retain it for safe identical retries.
Resume or abandon
Expired signed URLs are not permanent media addresses. Request fresh multipart
part URLs with POST /media/{id}/upload-parts using fromPart and toPart (an inclusive range of at most 64 parts). See the API reference for the bounded request
shape. Do not re-upload completed parts unnecessarily or complete multipart
assembly directly through storage: finalization is server controlled.
Use POST /media/{id}/abandon when canceling an incomplete upload. This releases
its reservation through the shared cleanup workflow. Session expiry or consumed
multipart state may require a new intent; do not guess storage object keys.
Temporary retention
GET /media/{id} returns status and dynamic deleteAfter information, not a
permanent public URL. Scheduled and in-flight uses protect media through the work.
Default policy retains unused draft media for 14 days, settled media for 72 hours,
and failed or ambiguous work for 7 days after the relevant attempt. Actual
retention depends on all remaining references; deleteAfter may be null.
Keep originals. If media is expired or deleting, upload it again before publishing.