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.
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.
- Call
get_onboarding_status. Readmedia.quota.availableBytes. - Call
start_media_uploadwith a stablerequestIdand a label. Send no field for the file type. - Send the file with one HTTP PUT to
directUpload.urlbeforeexpiresAt. SendContent-Type: image/jpegorContent-Type: image/png. SendContent-Lengthwith the exact size of the file in bytes. TheContent-Typedecides that the upload is an image. Never put bytes, a path or the signed URL in MCP arguments. - A reply of 200 returns
uploadwithstatus: "complete"andupload.asset. If the reply is lost, readget_media_uploaduntilupload.statusiscomplete. - Use
upload.asset.idin 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 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.
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 (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:
requiresOwneris true when a returned job awaits approval. Give itsapprovalUrlto the owner; reference renders usereference.approvalUrl, and exports have one URL per size. The owner approves in Jobs, or Agents → Requests when Requests is enabled.reasondescribes this call:ASKED,BUDGET_OFF,BILLING_OFF,BUDGET_LOWorNO_CREDITS. It is not a stored job decision. A replay of an older waiting job can returnrequiresOwner: truewithreason: null. Use the job status to decide the next action.budgetLeftis the calling grant's remaining decimal-string budget, ornullwhen disabled or set to No limit.creditsChargedis 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.
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 isMEDIA_TYPE_INVALID, orMEDIA_CONTENT_MISMATCHwhen the type is not the saved type. If a Studio render cannot decode the pixels, the code isMEDIA_RENDER_INVALID. If ffmpeg cannot use the overlay image of a classic render, the code isMEDIA_RENDER_FAILED. Replace the image, then render again. - The render ends
failedwithMEDIA_QUOTA_EXCEEDEDorPLAN_LIMIT_REACHEDwhen storage is full. Free space or change the plan, then render again. - A native render ends
failedwithMEDIA_RENDER_FAILEDafter 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
failedand 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. On desktop screens of 1024 px or wider, use Studio tour to explore the current view. See Studio tour.
For recipe recovery and external authoring, see 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.