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

```json
{
  "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](/docs/api) 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.
