> ## Documentation Index
> Fetch the complete documentation index at: https://mcp.shipcontent.com/llms.txt
> Use this file to discover all available pages before exploring further.

---
title: Get media into a workspace
description: Upload saved media, propose generation or renders, and use owner approval or an agent spending budget.
section: workflows
order: 30
status: implemented
mode: both
reviewed: 2026-11-19
sources: [src/lib/mcp/agent-spending-budget-definitions.ts, db/accounts.sql, src/lib/server/storage/media-video-limits.ts, src/lib/server/storage/media-video-frames.ts, db/media.sql, src/lib/media/provider-prompt.ts, src/lib/billing/quote.ts, src/lib/billing/media-quote.ts, db/billing.sql, src/lib/media/pricing-tiers.ts, db/retention.sql, src/lib/server/owner/owner-handler-media-routes.ts, src/lib/server/review/review-assets.ts, src/lib/server/storage/worker-output-storage.ts, src/lib/server/uploads/receive-upload.ts, src/lib/server/uploads/OwnerMediaUploads.ts, src/lib/docs/handoffs.ts, src/lib/server/media/media-agent-tools.ts, src/lib/server/media/MediaJobDatabase.ts, src/worker/MediaWorker.ts, src/lib/server/storage/media-object-render.ts, src/lib/mcp/agent-tools.ts, src/lib/server/mcp/AgentMcp.ts, src/lib/server/uploads/Uploads.ts, next.config.ts, scripts/check-standalone-media.mjs, src/lib/media/generation.ts, src/lib/media/types.ts, src/components/studio.tsx, src/components/composer.tsx, src/app/[workspace]/(app)/studio/page.tsx, src/components/studio/studio-page.tsx, src/components/studio/tour/studio-tour.tsx, src/components/studio/tour/progress.ts, src/components/studio/format-fit-chips.tsx, src/lib/media/formats.ts, src/lib/media/credits.ts, src/components/owner/post-video-upload.tsx, src/components/owner/upload-handoff-render.tsx, src/components/owner/jobs-menu-render.tsx, src/components/review/review-studio.tsx, src/lib/server/uploads/upload-failure.ts, src/lib/media/post-video-upload.ts, src/app/api/motion/route.ts, src/app/api/motion/export/route.ts, src/lib/server/media/MotionPlanner.ts, src/lib/server/media/MotionDocuments.ts, src/lib/server/media/MotionRenderer.ts, src/lib/media/motion.ts, src/lib/server/uploads/uploads-agent-tools.ts, src/lib/server/uploads/direct-upload-token.ts, src/app/mcp/uploads/[token]/route.ts, src/lib/billing/credit-catalogue-api.ts, src/worker/AccountVoiceProvider.ts, db/migrations/20261119T0450_agent_image_upload.sql, src/lib/uploads/uploads.ts, src/lib/server/uploads/DirectUploads.ts, src/lib/server/uploads/agent-image-upload.ts, src/lib/server/storage/media-object-inspection.ts, src/lib/server/storage/media-object-keys.ts, src/lib/marketing/post-catalogue.ts, src/lib/server/owner/studio-video-access.ts]
tools: [start_media_upload, get_media_upload, list_media_uploads, propose_generation, propose_render, get_media_job, list_media_jobs, get_onboarding_status, list_assets]
next: [/docs/workflows/videos, /docs/channels/instagram, /docs/contracts/request-ids]
---
MCP handles proposals and saved metadata. File bytes move through an HTTP upload or the signed-in owner browser, then into private storage.

## Upload an existing video

Call `get_onboarding_status` for the workspace media budget. Call `start_media_upload` using a stable `requestId` and label. Without Publish, give `uploadUrl` to the owner at `/media/upload` to select and send the file. With Publish, `directUpload` also contains a signed HTTP PUT URL and `expiresAt`, 15 minutes after the call. Send one MP4 up to 50 MiB to that URL with `Content-Type: video/mp4` and its `Content-Length`. Never include bytes, local paths or the signed URL in MCP arguments. Replay the same `requestId` and label to get a fresh direct URL after expiry. Turning off Publish blocks new direct uploads; disconnect invalidates the original grant. Read `get_media_upload` or `list_media_uploads` until the saved state is final, then use `list_assets`. A started upload is not an asset.

After a failed transfer, read the same upload request. If it is pending and accepts uploads, the owner can refresh its page, or an agent with Publish can use its unexpired direct URL, to send the same file again. Do not create a replacement request to recover a failed response. The production build checks that file inspection can load its required runtime files.

In Library, **Upload assets** accepts supported images, videos and audio, including when assets are already saved. Posts provides **Upload video** inside Create post and the current TikTok draft for one MP4 up to 50 MiB. A failed attachment keeps the saved video in Library and offers retry without another upload. Upload completion creates no publication job. Generated videos keep the 250 MiB limit and can be attached by saved asset ID without downloading or uploading again. See [TikTok publishing](/docs/channels/tiktok).

Updated 2026-11-09: each asset in Library and in Quick AI shows the date that it was saved. An open asset shows **Uploaded** or **Created** with that date.

Updated 2026-10-17: Library owner uploads, owner MP4 handoffs and direct MP4 uploads keep an uncertain storage result attached to the same upload. An expired receiver does not permit another write while that result is unresolved. MP4 requests report `canUpload: false` during that wait, and replaying `start_media_upload` does not issue a fresh direct URL. Confirmed stored bytes can be finalized through the same request without another storage write. Read the saved upload status before retrying; do not create a replacement request to bypass it. Canceling stops the asset from being added, but uncertain or stored bytes continue to count toward the media budget until their storage outcome is confirmed. A completed asset survives a lost completion reply.

Updated 2026-10-29: a new video can be at most 4096 pixels on its longest side and at most 8,847,360 pixels in total (4096×2160). This limit applies to new uploads by the owner or an agent, and to render sources. Every video track in the file must fit, a cover image included. A larger Library upload or render source fails with `MEDIA_LIMIT_EXCEEDED`. A larger MP4 upload from `start_media_upload` or `/media/upload` fails with `VIDEO_INVALID`. A saved video that is already larger stays saved and can still be published, but it cannot be a render source. Export the video at a smaller size, then upload it again.

## Upload an existing image

An agent with Publish can upload one JPEG or PNG image with the same tools as a video. Without Publish, the owner adds images in Library with **Upload assets**. The owner page at `uploadUrl` (`/media/upload`) takes an MP4 only. It does not take images.

1. Call `get_onboarding_status`. Read `media.quota.availableBytes`.
2. Call `start_media_upload` with a stable `requestId` and a label. Send no field for the file type.
3. Send the file with one HTTP PUT to `directUpload.url` before `expiresAt`. Send `Content-Type: image/jpeg` or `Content-Type: image/png`. Send `Content-Length` with the exact size of the file in bytes. The `Content-Type` decides that the upload is an image. Never put bytes, a path or the signed URL in MCP arguments.
4. A reply of 200 returns `upload` with `status: "complete"` and `upload.asset`. If the reply is lost, read `get_media_upload` until `upload.status` is `complete`.
5. Use `upload.asset.id` in a post.

An image has the same limits as an image that the owner uploads in Library:

| Rule | Value |
| --- | --- |
| Types | `image/jpeg` and `image/png` |
| Size | At most 30 MiB (31,457,280 bytes) |
| Pixels | At most 40,000,000 (width × height) |
| Frames | One. An animated file is refused. |

The server does not trust `Content-Type`. It reads the real type, width and height from the bytes. `get_media_upload` returns `upload.asset` with `kind: "image"`, `contentType`, `size`, `width`, `height` and no `duration`. The asset name is `upload.jpg` or `upload.png`. The saved asset has the same metadata as an owner image. The `size` counts in the workspace media budget, as a video does.

A refused image saves no asset and holds no budget. The upload returns to `pending` with `manifest: null`. Send the right file to the same URL. Each refusal returns `{ code, error }`.

| Status and `code` | Cause | Next action |
| --- | --- | --- |
| 411 `CONTENT_LENGTH_REQUIRED` | No `Content-Length`, or its value is not a positive whole number. | Send `Content-Length` with the exact size. |
| 413 `UPLOAD_TOO_LARGE` | `Content-Length` is more than 30 MiB. | Export a smaller image. |
| 415 `MEDIA_TYPE_INVALID` | `Content-Type` is another `image/` type, such as `image/webp` or `image/jpg`. Or the bytes are not a readable one-frame JPEG or PNG. Or the image has more than 40,000,000 pixels. | Send a JPEG or PNG with a correct type, one frame and fewer pixels. |
| 415 `MEDIA_TYPE_MISMATCH` | The bytes are a JPEG or a PNG, but not the type in `Content-Type`. | Send the type that matches the file. |
| 400 `MEDIA_UPLOAD_INCOMPLETE` | The body has fewer bytes than `Content-Length`. | Send the whole file again to the same URL. |
| 413 `MEDIA_LIMIT_EXCEEDED` | The body has more bytes than `Content-Length`. | Send `Content-Length` equal to the file size. |
| 409 `MEDIA_QUOTA_EXCEEDED` | The file does not fit in the workspace media budget. | Read `media.quota.availableBytes`. Free space or send a smaller file. |
| 403 `PUBLISH_NOT_ALLOWED` | The agent has no Publish permission. | Ask the owner to allow Publish. |
| 403 `UPLOAD_URL_INVALID` | The URL is not valid or it expired. | Call `start_media_upload` again with the same `requestId` and label. |
| 409 `UPLOAD_CLOSED` | The upload is complete. | Read `get_media_upload`. Do not send the file again. |
| 409 `UPLOAD_MANIFEST_CONFLICT` | This upload is bound to a different file. | Start a new upload for the new file. |

A request with `video/mp4`, `application/octet-stream` or no `Content-Type` follows the video rules. See `UPLOAD_BUSY`, `MEDIA_UPLOAD_BUSY` and `STORAGE_OPERATION_UNRESOLVED` in [Error codes](/docs/contracts/errors) for a transfer that cannot start now.

An image asset can attach to an image or carousel post, or to an Instagram story. Publishing is implemented today for an Instagram image, carousel and story, a Facebook image, a Threads image and an X image. Other channels keep the image formats as drafts. Read `get_post_catalogue` for the current list. Each channel checks the file again when you publish. Instagram takes JPEG only, at most 8,000,000 bytes. Threads takes JPEG or PNG, at most 8,000,000 bytes. Facebook takes JPEG or PNG, under 10,000,000 bytes. X takes JPEG or PNG, at most 5 MiB. A saved image that a channel refuses stays saved.

Updated 2026-11-19: an agent with Publish can upload a JPEG or PNG image with `start_media_upload`. A request that sends only `video/mp4` works as before.

## Propose generated media

Updated 2026-11-19: image generation is open to every owner. Video and voice generation, renders and project work need the owner in the server setting `SHIPCONTENT_STUDIO_VIDEO_USERS`. For another owner, `propose_generation` with a video or voice mode and `propose_render` return `NOT_FOUND` before anything is saved, and the owner cannot approve a waiting video, voice or render job. Studio shows **Video and carousels are coming soon.** in place of those actions.

In Studio, **Make it fit** shows chips for single images, carousels, videos and Stories. A check marks a format that fits the selected media type and ratio. Other chips show the required ratio or **Use Images** / **Use Clips**. A carousel needs added slides. These chips show format fit; they do not confirm channel publication. Quick AI shows estimated credits on **Generate**. See [Studio credit estimates](/docs/workflows/videos#start-a-project).

Updated 2026-11-07: call `propose_generation` with a stable `input.clientRequestId`. After a lost reply, repeat identical input and the same ID to recover the saved job. With an eligible [spending budget](/docs/contracts/grants#spending-budget) (No limit skips the budget check), a new job reserves credits and queues without owner approval. Otherwise it waits without a new hold. Pass top-level `askOwner: true` to request approval for new jobs. A replay preserves saved jobs; it cannot approve a waiting job or stop a queued one.

The same decision fields apply to `propose_render`, `export_project` and `prepare_seedance_reference`:

- `requiresOwner` is true when a returned job awaits approval. Give its `approvalUrl` to the owner; reference renders use `reference.approvalUrl`, and exports have one URL per size. The owner approves in **Jobs**, or **Agents → Requests** when Requests is enabled.
- `reason` describes this call: `ASKED`, `BUDGET_OFF`, `BILLING_OFF`, `BUDGET_LOW` or `NO_CREDITS`. It is not a stored job decision. A replay of an older waiting job can return `requiresOwner: true` with `reason: null`. Use the job status to decide the next action.
- `budgetLeft` is the calling grant's remaining decimal-string budget, or `null` when disabled or set to No limit. `creditsCharged` is a decimal string for new credit holds reserved by this call. It is `"0"` for a replay or an approval fallback, and is not the final settled charge. Job reads expose no budget fields.

For an approval, read `get_media_job.quote`. The owner approves the saved input hash and that displayed quote. A price change requires another owner click. If the display price is unavailable, `quote` is null; approval still checks active billing rules. A waiting proposal starts provider work only after approval. An export batch queues all new sizes together only if the budget and billing checks allow them; otherwise its new sizes wait without new holds. Existing replayed sizes keep their saved state.

A proposal can make images, a video, or a voiceover. For a voiceover, use mode `text-to-speech` with model `elevenlabs-tts`, the script in `prompt` and an optional `voice`. The result is an audio asset. Updated 2026-11-02: the voiceover is made by ElevenLabs (Eleven v4) with the server `ELEVENLABS_API_KEY`, not through fal.ai. The script can hold audio tags such as `[excited]` or `[short pause]`; each tag counts as characters. Updated 2026-11-10: an owner can also pick a voice from their own connected ElevenLabs account in Studio. Agents and drafts cannot name such a voice; `voice` takes only the built-in voices.

After a disconnect, call `list_media_jobs` and find the job by its `requestId`. Then call `get_media_job` with that job ID. These reads do not start provider work. If the job is `unknown`, the provider submission has no confirmed result. Keep the same job ID and ask the owner to reconcile it. Do not generate again to repair a failed download or lost reply. Unknown receipt recovery uses the same bounded attempt budget after workspace authority returns; a parked job cannot restart normal polling. A confirmed success schedules file collection only for a nonterminal job with current source and membership authority. Cancelled and failed jobs remain terminal. Confirmed provider failure finishes an active recovery job as failed.

Updated 2026-10-23: the provider charges by quality and resolution, so each tier has its own `quote.actionKey`. A GPT Image request uses `media.generate.<model>.<quality>`, for example `media.generate.flare.high`. FLUX Schnell has one price. A video request uses `media.generate.<model>.<resolution>`, for example `media.generate.seedance-2.0.720p`. A reference-to-video request with reference videos uses a key that ends in `.video-reference`. Its `quantity` is the output seconds plus the total seconds of the reference videos, rounded up once. The server reads the reference seconds from the saved assets and rejects a quote that differs. For duration `auto`, the final charge is the inspected output seconds (at most 15) plus the same reference seconds.

Updated 2026-10-23: the provider also charges for the input of a GPT Image request. A quote with input has a `lines` list. Each line has `actionKey`, `quantity` and `priceVersion`. `credits` is the total of the main line and all lines, rounded up once. An `edit-image` request has a `media.generate.<model>.reference-image` line: its `quantity` is the number of reference images. Every GPT Image request has a `media.generate.<model>.prompt-text` line: its `quantity` is the UTF-8 bytes of the prompt, plus the brief and 89 bytes of wrapper text when the brief is not empty. FLUX Schnell has no lines. The server computes the lines from the saved input and rejects a quote that leaves out a line or has a different quantity with `PRICE_CHANGED`. The job holds the total and uses it all when the provider succeeds.

Owner generation, voiceover and render requests send a top-level `quote` with `actionKey`, `quantity`, `priceVersion`, `credits` and, for a GPT Image request, `lines`. Keep it outside the creative input. `priceVersion` is the action version, not the catalogue fingerprint. After a lost response, keep the same request ID, input and quote. A replay returns the saved job without another hold.

For video duration `auto`, the quote reserves up to 15 seconds. The final charge uses the inspected output duration, rounded up to whole seconds and capped at 15, at the accepted rate of its priced reservation. An optional quote saved while billing is off is comparison evidence only; with no reservation it creates no settlement or historical-price requirement. Existing priced reservations keep their terms even if billing is later turned off. A temporary failed download gets up to six collection attempts with increasing delays. Permanent content errors finish collection as failed; exhausted retries require operator reconciliation. Missing duration keeps the reservation. It does not start another generation. Fixed-quantity provider success is charged before file collection.

Updated 2026-10-17: generated media, voiceovers and native renders keep an uncertain file write on the same job. Recovery reads the saved destination and does not send another write while the first result is unresolved. Keep the job ID; do not generate again. A storage fence can stop saving the asset while confirmed provider work remains charged. For automatic-duration video, a confirmed measurement settles the accepted charge before storage admission. A failed file save does not reverse that charge.

An unstarted job may return to `awaiting_approval` when billing is enabled or its hold expires. The saved reason is `MEDIA_APPROVAL_REQUIRED` after a mode change or `MEDIA_APPROVAL_EXPIRED` after the deliberate one-hour hold expires. Read its current quote and ask the owner to approve again. Expiry does not start another paid submission, even when a spending budget is on. A generation cannot be cancelled after provider submission starts, and a render cannot be cancelled after native execution starts: `MEDIA_SUBMISSION_STARTED` leaves accounting recovery active. See [error codes](/docs/contracts/errors).

## Propose a render

Call `propose_render` with a stable `input.clientRequestId` for a local `ffmpeg` composition. It waits for owner approval unless an eligible spending budget permits the new render; top-level `askOwner: true` requests approval. A render uses saved inputs and does not call the generation provider. Its current price is zero credits, but it still needs the AI plan permission when billing is enforced. When owner approval is required, its displayed quote must accompany approval; a later positive price requires a new owner decision. When making a Seedance reference video or still, the drawer shows the reference-render credits separately from generation credits. **Render reference and generate** accepts both displayed costs. After a disconnect, use `list_media_jobs` and its `requestId` to find the job. Read `get_media_job` for the output asset ID.

If source access ends after a native render lease expires, complete durable output slots settle the accepted render charge. Incomplete native work releases its unused hold; placeholder slots alone do not prove completion.

Updated 2026-10-29: a native render stops when a retry cannot succeed.

- A broken image source ends the render `failed`. If the server cannot read the file type or the image header, the code is `MEDIA_TYPE_INVALID`, or `MEDIA_CONTENT_MISMATCH` when the type is not the saved type. If a Studio render cannot decode the pixels, the code is `MEDIA_RENDER_INVALID`. If ffmpeg cannot use the overlay image of a classic render, the code is `MEDIA_RENDER_FAILED`. Replace the image, then render again.
- The render ends `failed` with `MEDIA_QUOTA_EXCEEDED` or `PLAN_LIMIT_REACHED` when storage is full. Free space or change the plan, then render again.
- A native render ends `failed` with `MEDIA_RENDER_FAILED` after six failed attempts. An error or an expired lease is one failed attempt. A slot that saves without an error does not count.
- The server settles the credit hold of a failed render one time. If every output slot saved before the last attempt, the render charge stays. If not, the server releases the hold.
- If the hold was already settled, for example by support, the render ends `failed` and the hold does not change.
- A paid generation that full storage refuses keeps its collection attempts. When space is free before the last attempt, the job completes. The provider does not charge again.

Saved asset metadata does not prove that bytes are currently readable or that Instagram accepts the media. Readiness and approval are separate steps. Never put file paths, provider credentials or signed URLs into MCP arguments. The direct upload URL is a temporary bearer credential: use it only for that upload.

## Make a video, carousel, image or Story

Updated 2026-11-19: for an owner who is not in `SHIPCONTENT_STUDIO_VIDEO_USERS`, Studio shows **Make images** and **Skills** only. The Quick AI Clips tab, **Make video**, the video, carousel and Story formats, and the MP4 export in Review are not shown.

At `/{n}/studio`, select a format and make the project there. Edit it, convert it and export each size in the same page. See [Make a Studio project](/docs/workflows/videos). On desktop screens of 1024 px or wider, use **Studio tour** to explore the current view. See [Studio tour](/docs/workflows/videos#studio-tour).

For recipe recovery and external authoring, see [video skills](/docs/workflows/videos#video-skills).

Updated 2026-10-16: `get_onboarding_status` returns saved and reserved media bytes. In enforce mode, `limitBytes` uses the current storage entitlement. An unbounded limit has `limitBytes: null` and `availableBytes: null`. A finite limit can be below existing usage after a downgrade; `availableBytes` is then zero. Existing files remain readable, and deletion or shrinking can reduce usage. New owner uploads, agent uploads, generated assets and website assets share this check. Finishing an exact reserved upload consumes its reservation once. Off and shadow modes keep the legacy upload ceiling.


Updated 2026-10-17: imported website images retain their website asset IDs. Private previews use the saved workspace object key and require the signed-in owner. PNG, JPEG and WebP images saved through the tracked website path can use this preview.

Updated 2026-10-17: a completed upload is a saved operation record. If its file becomes unavailable through retention, `asset` is `null` and `canUpload` remains false for MP4 requests. Replaying the request returns the same history and cannot restore the old bytes. Use only a non-null `asset.id`. Media-job `assetIds` omit unavailable outputs while the original job status, request ID and accepted quote remain. Worker recovery stops before reading or rewriting a retired destination; it never submits a replacement generation.

Updated 2026-10-17: confirmed retention accounting also removes the exact original reservation for files that never became saved assets. Other reservations remain. An unresolved or conflicting deletion does not release reserved bytes. Quota release does not mark a PUT as rolled back or reopen its upload. A retired MP4 receiver keeps `canUpload: false` after access returns.

Updated 2026-10-31: when Spanish is available for your account, the Studio tour, Library, Review board, the header Jobs menu, the upload page at `/media/upload` and Upload video in Posts show your account language, English or Spanish. A saved media failure that the app knows, such as an expired approval, held credits, a failed download or an unconfirmed submission, shows its recovery step in your language. Other saved failures show a general recovery sentence in Spanish.

A language change sends no generation, render or upload request and does not start another provider job. Upload failures from the server show in your language when the code is known. File names, prompts, model names, provider values and the text of a saved job stay as saved. Tool output, error codes and the text agents read stay in English.
