AiVideoEditor
Start for free
Menu

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

  1. Call POST /api/v1/media/upload-intents with filename, declared MIME and byte count. Save the returned assetId and sessionId as separate identities.
  2. Inspect method. For presigned_put, upload the whole file to uploadUrl using the returned headers. For multipart_initiated, split using partSizeBytes, upload each numbered part to its returned URL and retain its ETag receipt. Never add the AiVideoEditor bearer key to storage requests.
  3. Finalize at POST /api/v1/media/{assetId}/finalize with sessionId and, for multipart, multipart.parts containing each partNumber and etag.
  4. 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.