TokenTable Unified API Reference

GET /v1/models

models · synchronous · none · Availability: public

HTTP statuses: 200, 429

Request (application/json)

Response (application/json)

• object:string · required
• data:model[] · required · owned_by is always "tokentable"; it does not identify the model vendor or the serving provider. Read the model brand from the id.

Errors: 429 · fastify · A rate or plan limit was reached. · Contract semantics: global rate limit reached

POST /v1/chat/completions

chatCompletions · streaming-optional · bearer · Availability: public

HTTP statuses: 200, 400, 401, 402, 403, 409, 413, 415, 422, 429, 502, 503, 504

Protocol statuses: 400, 413, 415

Request (application/json)

• model:string · optional · Omit it or send "auto" for smart routing, or send an id from GET /v1/models. An id that is not in the catalog is not rejected: the request is routed as auto, which may use a free side model. Check the id against GET /v1/models first. Unlike POST /v1/media/image, an unknown chat model id does not return 400.
• messages:message[] · required · For papaya-1.0-spicy, images go in image_url parts as either a public https URL or a base64 data URL (data:image/jpeg;base64,...), so an image can be uploaded directly; the whole request must stay under 8 MiB. A user message may also carry a UTF-8 text file (.md, .markdown or .txt, up to 300 KB) as a file part: {"type":"file","file":{"filename":"chapter1.md","file_data":"data:text/markdown;base64,..."}}. The file text is passed to the model inside that message, and the whole request must still fit the model; split longer files and send the parts in separate requests. file_id is not supported. It may also carry one MP4 video as {"type":"video_url","video_url":{"url":"https://..."}} (public https URL, up to 50 MB and 3 minutes; stream: true is required): TokenTable downloads it and sends 12 evenly spaced frames, so the model reads the pictures only, not the audio or dialogue, and the response carries X-TT-Video-Audio: not-transcribed. Put any dialogue you need in the text. A video in an earlier message is not sent again. Other models do not read file or video_url parts.
• stream:boolean · optional · Use stream: true for long outputs. A non-streaming request that has not finished after about two minutes can be cut off at the network edge with HTTP 524 and an HTML body; a streamed response keeps sending data and is not cut off.
• temperature:number · optional
• max_tokens:integer · optional · Upper limit on output tokens; on models that reason, reasoning tokens count toward it. It is forwarded to the model. If the model rejects the value as too large, the request is sent once more without it. Without it, the model decides the length (Claude models: up to 32000 tokens).
• tools:tool[] · optional
• tool_choice:string|tool_choice · optional
• response_format:response_format · optional · Not forwarded to any model at this time: json_object and json_schema (including strict) do not constrain the output. Ask for JSON in the prompt and remove Markdown code fences before parsing. Models that start honouring it will be listed in the CHANGELOG.
• modalities:string[] · optional · Set exactly ["text"] to bypass media intent detection.
• X-TokenTable-Modalities:header:text · optional · Set to text to bypass media intent detection on this request.

Response (application/json or text/event-stream)

• id:string · required
• object:string · required
• created:integer · required
• model:string · required · Non-streaming responses echo the model value you sent; it does not identify the model that actually served the request.
• choices:choice[] · required
• usage:usage · optional

Errors: 400 · openai · Request or schema validation failed. · Contract semantics: invalid request

Errors: 401 · openai · The credential is invalid or expired. · Contract semantics: invalid or expired API key

Errors: 402 · openai · Quota or points are insufficient. · Contract semantics: quota rejected

Errors: 403 · openai · The model or entitlement was rejected. · Contract semantics: model or entitlement rejected

Errors: 429 · openai · A rate or plan limit was reached. · Contract semantics: rate or plan limit reached

Errors: 502 · openai · Upstream generation, delivery, or settlement failed. · Contract semantics: upstream generation failed

Errors: 503 · openai · The service is not configured or unavailable. · Contract semantics: service not configured or unavailable

Errors: 504 · openai · Upstream generation timed out. · Contract semantics: upstream generation timed out

Errors: 403 · openai · The model or entitlement was rejected. · Contract semantics: Starter video generation requires purchased points before dispatch · Identifier: error.code=video_generation_requires_payment

Errors: 400 · openai · Request or schema validation failed. · Contract semantics: papaya-1.0-spicy file part that is empty or not valid base64 or UTF-8 text · Identifier: error.code=invalid_file_encoding

Errors: 400 · openai · Request or schema validation failed. · Contract semantics: papaya-1.0-spicy file part sent as file_id or without file_data · Identifier: error.code=unsupported_file_type

Errors: 400 · openai · Request or schema validation failed. · Contract semantics: papaya-1.0-spicy request that is too long for the model once the file is included; split the file · Identifier: error.code=context_length_exceeded

Errors: 413 · openai · The body or image is too large. · Contract semantics: papaya-1.0-spicy file part larger than 300 KB · Identifier: error.code=file_too_large

Errors: 415 · openai · The media type is unsupported. · Contract semantics: papaya-1.0-spicy file part that is not a .md, .markdown or .txt text file · Identifier: error.code=unsupported_file_type

Errors: 400 · openai · Request or schema validation failed. · Contract semantics: papaya-1.0-spicy video_url request without stream: true · Identifier: error.code=stream_required

Errors: 400 · openai · Request or schema validation failed. · Contract semantics: papaya-1.0-spicy video_url that is not a public https URL on the default port · Identifier: error.code=invalid_video_url

Errors: 400 · openai · Request or schema validation failed. · Contract semantics: papaya-1.0-spicy request with more than one video in the latest user message · Identifier: error.code=too_many_videos

Errors: 400 · openai · Request or schema validation failed. · Contract semantics: papaya-1.0-spicy video that could not be downloaded (HTTP error, unreachable host, too many redirects or timeout) · Identifier: error.code=video_download_failed

Errors: 400 · openai · Request or schema validation failed. · Contract semantics: papaya-1.0-spicy video longer than 3 minutes · Identifier: error.code=video_too_long

Errors: 413 · openai · The body or image is too large. · Contract semantics: papaya-1.0-spicy video larger than 50 MB · Identifier: error.code=video_too_large

Errors: 415 · openai · The media type is unsupported. · Contract semantics: papaya-1.0-spicy video that is not a readable MP4 · Identifier: error.code=unsupported_video_type

Errors: 503 · openai · The service is not configured or unavailable. · Contract semantics: papaya-1.0-spicy video input temporarily unavailable or busy; retry later · Identifier: error.code=video_processing_unavailable

Errors: 409 · openai · Handle this error according to the contract. · Contract semantics: final media confirmation already submitted

Errors: 429 · openai · A rate or plan limit was reached. · Contract semantics: A select-only text model (papaya-1.0-spicy or a Doubao text model) was named after today's main-dish allowance ran out; it is not replaced with another model. Retry tomorrow, buy a top-up or pick another model · Identifier: error.code=explicit_model_daily_limit

Errors: 402 · openai · Quota or points are insufficient. · Contract semantics: A select-only text model (papaya-1.0-spicy or a Doubao text model) was named after the monthly main-dish quota and top-up balance ran out; it is not replaced with another model. Upgrade the plan, buy a top-up or pick another model · Identifier: error.code=explicit_model_quota_exhausted

Errors: 413 · openai · The body or image is too large. · Contract semantics: On the free plan, a select-only text model (papaya-1.0-spicy or a Doubao text model) was named with an input longer than the pinned-model limit; it is not replaced with TokenTable Auto. Shorten the input or upgrade the plan · Identifier: error.code=starter_explicit_input_too_large

Errors: 422 · native · The model refused this input (content review or limits); change the input before resubmitting. · Contract semantics: the prompt for z-image-spicy, qwen-image-edit-spicy, wan2.7-i2v-spicy, w3.0-video or w3.0-video-pro asks for content the model does not generate, such as minors or non-consensual content; refused before any points are held. The body is {error, reason, message} with reason input_policy, not the error object of this format. Change the prompt and submit again · Identifier: error=input_rejected

POST /v1/responses

responses · streaming-optional · bearer or x-api-key header · Availability: public

HTTP statuses: 200, 400, 401, 402, 403, 413, 415, 422, 429, 502, 503, 504

Protocol statuses: 400, 413, 415

Request (application/json)

• model:string · optional
• input:string|input_item[] · required
• instructions:string · optional
• stream:boolean · optional
• tools:tool[] · optional
• tool_choice:string|tool_choice · optional
• temperature:number · optional
• top_p:number · optional
• max_output_tokens:integer · optional
• modalities:string[] · optional · Set exactly ["text"] to bypass media intent detection.
• X-TokenTable-Modalities:header:text · optional · Set to text to bypass media intent detection on this request.

Response (application/json or text/event-stream)

• id:string · required
• object:string · required
• created_at:integer · required
• status:string · required
• model:string · required
• output:output_item[] · optional
• output_text:string · optional
• usage:usage · optional

Errors: 400 · openai · Request or schema validation failed. · Contract semantics: invalid request

Errors: 401 · openai · The credential is invalid or expired. · Contract semantics: invalid or expired API key

Errors: 402 · openai · Quota or points are insufficient. · Contract semantics: quota rejected

Errors: 403 · openai · The model or entitlement was rejected. · Contract semantics: model or entitlement rejected

Errors: 429 · openai · A rate or plan limit was reached. · Contract semantics: rate or plan limit reached

Errors: 502 · openai · Upstream generation, delivery, or settlement failed. · Contract semantics: upstream generation failed

Errors: 503 · openai · The service is not configured or unavailable. · Contract semantics: service not configured or unavailable

Errors: 504 · openai · Upstream generation timed out. · Contract semantics: upstream generation timed out

Errors: 403 · openai · The model or entitlement was rejected. · Contract semantics: Starter video generation requires purchased points before dispatch · Identifier: error.code=video_generation_requires_payment

Errors: 422 · native · The model refused this input (content review or limits); change the input before resubmitting. · Contract semantics: the prompt for z-image-spicy, qwen-image-edit-spicy, wan2.7-i2v-spicy, w3.0-video or w3.0-video-pro asks for content the model does not generate, such as minors or non-consensual content; refused before any points are held. The body is {error, reason, message} with reason input_policy, not the error object of this format. Change the prompt and submit again · Identifier: error=input_rejected

POST /v1/messages

anthropicMessages · streaming-optional · bearer or x-api-key header · Availability: public

HTTP statuses: 200, 400, 401, 402, 403, 413, 415, 422, 429, 502, 503, 504

Protocol statuses: 400, 413, 415

Request (application/json)

• model:string · optional
• messages:message[] · required
• max_tokens:integer · optional
• system:string|content_block[] · optional
• stream:boolean · optional
• tools:tool[] · optional
• tool_choice:tool_choice · optional
• temperature:number · optional
• top_p:number · optional
• stop_sequences:string[] · optional
• modalities:string[] · optional · Set exactly ["text"] to bypass media intent detection.
• X-TokenTable-Modalities:header:text · optional · Set to text to bypass media intent detection on this request.

Response (application/json or text/event-stream)

• id:string · required
• type:string · required
• role:string · required
• model:string · required
• content:content_block[] · required
• stop_reason:string|null · optional
• stop_sequence:string|null · optional
• usage:usage · optional

Errors: 400 · anthropic · Request or schema validation failed. · Contract semantics: invalid request

Errors: 401 · anthropic · The credential is invalid or expired. · Contract semantics: invalid API key

Errors: 402 · anthropic · Quota or points are insufficient. · Contract semantics: quota rejected by the underlying chat endpoint

Errors: 403 · anthropic · The model or entitlement was rejected. · Contract semantics: model or entitlement rejected by the underlying chat endpoint

Errors: 429 · anthropic · A rate or plan limit was reached. · Contract semantics: rate or plan limit reached

Errors: 502 · anthropic · Upstream generation, delivery, or settlement failed. · Contract semantics: compatibility loopback or upstream generation failed

Errors: 503 · anthropic · The service is not configured or unavailable. · Contract semantics: underlying service unavailable

Errors: 504 · anthropic · Upstream generation timed out. · Contract semantics: upstream generation timed out

Errors: 403 · anthropic · The model or entitlement was rejected. · Contract semantics: Starter video generation requires purchased points before dispatch · Identifier: error.code=video_generation_requires_payment

Errors: 422 · native · The model refused this input (content review or limits); change the input before resubmitting. · Contract semantics: the prompt for z-image-spicy, qwen-image-edit-spicy, wan2.7-i2v-spicy, w3.0-video or w3.0-video-pro asks for content the model does not generate, such as minors or non-consensual content; refused before any points are held. The body is {error, reason, message} with reason input_policy, not the error object of this format. Change the prompt and submit again · Identifier: error=input_rejected

POST /v1/messages/count_tokens

anthropicCountTokens · synchronous · none · Availability: public

HTTP statuses: 200, 400, 413, 415

Protocol statuses: 400, 413, 415

Request (application/json)

• messages:message[] · optional
• system:string|content_block[] · optional
• tools:tool[] · optional

Response (application/json)

• input_tokens:integer · required

POST /v1/images/generations

openAiImages · synchronous · bearer · Availability: public

HTTP statuses: 200, 400, 401, 402, 403, 413, 415, 422, 429, 502, 503, 504

Protocol statuses: 400, 413, 415

Request (application/json)

• prompt:string · required
• n:integer · optional
• size:string · optional
• response_format:string · optional
• model:string · optional · Compatibility field: ignored; this endpoint uses its fixed image model. Use GET /v1/me/model-catalog and the native media endpoint for model selection.

Response (application/json)

• created:integer · optional
• data:image_result[] · required · The request waits up to 150 seconds for the image. A response that has not started after about two minutes can be cut off at the network edge with HTTP 524 and an HTML body; held points are then released where possible, and a case that cannot be confirmed stays held for reconciliation. For slow generations use POST /v1/media/image, where Seedream 5.0 pro and flash and the Spicy Seedream models accept async: true.

Errors: 400 · openai · Request or schema validation failed. · Contract semantics: invalid request

Errors: 401 · openai · The credential is invalid or expired. · Contract semantics: invalid or expired API key

Errors: 402 · openai · Quota or points are insufficient. · Contract semantics: insufficient quota · Identifier: error.type=insufficient_quota

Errors: 403 · openai · The model or entitlement was rejected. · Contract semantics: model or entitlement rejected

Errors: 429 · openai · A rate or plan limit was reached. · Contract semantics: rate or plan limit reached

Errors: 502 · openai · Upstream generation, delivery, or settlement failed. · Contract semantics: upstream generation failed

Errors: 503 · openai · The service is not configured or unavailable. · Contract semantics: service not configured or unavailable

Errors: 504 · openai · Upstream generation timed out. · Contract semantics: upstream generation timed out

Errors: 502 · openai · Upstream generation, delivery, or settlement failed. · Contract semantics: the image was generated but could not be stored for TokenTable delivery; held points are refunded where possible · Identifier: error.message=image_delivery_failed

Errors: 502 · openai · Upstream generation, delivery, or settlement failed. · Contract semantics: generation failed; the response never carries the upstream message, and held points are refunded where possible · Identifier: error.message=image_generation_failed

Errors: 502 · openai · Upstream generation, delivery, or settlement failed. · Contract semantics: the refund of held points could not be confirmed; the points stay held for reconciliation · Identifier: error.message=settlement_pending

Errors: 422 · native · The model refused this input (content review or limits); change the input before resubmitting. · Contract semantics: the prompt for z-image-spicy, qwen-image-edit-spicy, wan2.7-i2v-spicy, w3.0-video or w3.0-video-pro asks for content the model does not generate, such as minors or non-consensual content; refused before any points are held. The body is {error, reason, message} with reason input_policy, not the error object of this format. Change the prompt and submit again · Identifier: error=input_rejected

POST /v1/video/generations

openAiVideo · synchronous · bearer · Availability: public

HTTP statuses: 200, 400, 401, 402, 403, 413, 415, 422, 429, 502, 503, 504

Protocol statuses: 400, 413, 415

Request (application/json)

• prompt:string · required
• model:string · optional · Compatibility field: ignored; this endpoint uses its fixed video model.
• size:string · optional
• duration:integer · optional

Response (application/json)

• created:integer · optional
• data:video_result[] · required · data[].url is a TokenTable delivery reference, not a direct download link: a plain GET on it returns 410. API keys download through the delivery descriptor.
• delivery:api_delivery_descriptor · optional · Present for API keys. POST its body to the path with the same Authorization header and no cookies; the grant expires after one hour.

Errors: 400 · openai · Request or schema validation failed. · Contract semantics: invalid request

Errors: 401 · openai · The credential is invalid or expired. · Contract semantics: invalid or expired API key

Errors: 402 · openai · Quota or points are insufficient. · Contract semantics: insufficient quota · Identifier: error.type=insufficient_quota

Errors: 403 · openai · The model or entitlement was rejected. · Contract semantics: model or entitlement rejected

Errors: 429 · openai · A rate or plan limit was reached. · Contract semantics: rate or plan limit reached

Errors: 502 · openai · Upstream generation, delivery, or settlement failed. · Contract semantics: upstream generation failed

Errors: 503 · openai · The service is not configured or unavailable. · Contract semantics: service not configured or unavailable

Errors: 504 · openai · Upstream generation timed out. · Contract semantics: upstream generation timed out

Errors: 403 · openai · The model or entitlement was rejected. · Contract semantics: Starter video generation requires purchased points before dispatch · Identifier: error.code=video_generation_requires_payment

Errors: 502 · openai · Upstream generation, delivery, or settlement failed. · Contract semantics: video generation failed; the response never carries the upstream message · Identifier: error.message=video_generation_failed

Errors: 503 · native · The service is not configured or unavailable. · Contract semantics: the video was generated but a TokenTable delivery reference could not be issued; points are not captured · Identifier: error=video_delivery_unavailable

Errors: 422 · native · The model refused this input (content review or limits); change the input before resubmitting. · Contract semantics: the prompt for z-image-spicy, qwen-image-edit-spicy, wan2.7-i2v-spicy, w3.0-video or w3.0-video-pro asks for content the model does not generate, such as minors or non-consensual content; refused before any points are held. The body is {error, reason, message} with reason input_policy, not the error object of this format. Change the prompt and submit again · Identifier: error=input_rejected

POST /v1/videos/generations

openAiVideosAlias · synchronous · bearer · Availability: public

HTTP statuses: 200, 400, 401, 402, 403, 413, 415, 422, 429, 502, 503, 504

Protocol statuses: 400, 413, 415

Request (application/json)

• prompt:string · required
• model:string · optional · Compatibility field: ignored; this endpoint uses its fixed video model.
• size:string · optional
• duration:integer · optional

Response (application/json)

• created:integer · optional
• data:video_result[] · required · data[].url is a TokenTable delivery reference, not a direct download link: a plain GET on it returns 410. API keys download through the delivery descriptor.
• delivery:api_delivery_descriptor · optional · Present for API keys. POST its body to the path with the same Authorization header and no cookies; the grant expires after one hour.

Errors: 400 · openai · Request or schema validation failed. · Contract semantics: invalid request

Errors: 401 · openai · The credential is invalid or expired. · Contract semantics: invalid or expired API key

Errors: 402 · openai · Quota or points are insufficient. · Contract semantics: insufficient quota · Identifier: error.type=insufficient_quota

Errors: 403 · openai · The model or entitlement was rejected. · Contract semantics: model or entitlement rejected

Errors: 429 · openai · A rate or plan limit was reached. · Contract semantics: rate or plan limit reached

Errors: 502 · openai · Upstream generation, delivery, or settlement failed. · Contract semantics: upstream generation failed

Errors: 503 · openai · The service is not configured or unavailable. · Contract semantics: service not configured or unavailable

Errors: 504 · openai · Upstream generation timed out. · Contract semantics: upstream generation timed out

Errors: 403 · openai · The model or entitlement was rejected. · Contract semantics: Starter video generation requires purchased points before dispatch · Identifier: error.code=video_generation_requires_payment

Errors: 502 · openai · Upstream generation, delivery, or settlement failed. · Contract semantics: video generation failed; the response never carries the upstream message · Identifier: error.message=video_generation_failed

Errors: 503 · native · The service is not configured or unavailable. · Contract semantics: the video was generated but a TokenTable delivery reference could not be issued; points are not captured · Identifier: error=video_delivery_unavailable

Errors: 422 · native · The model refused this input (content review or limits); change the input before resubmitting. · Contract semantics: the prompt for z-image-spicy, qwen-image-edit-spicy, wan2.7-i2v-spicy, w3.0-video or w3.0-video-pro asks for content the model does not generate, such as minors or non-consensual content; refused before any points are held. The body is {error, reason, message} with reason input_policy, not the error object of this format. Change the prompt and submit again · Identifier: error=input_rejected

POST /v1/media/image

nativeImage · asynchronous · bearer · Availability: public

HTTP statuses: 200, 202, 400, 401, 402, 403, 413, 415, 422, 429, 500, 502, 503, 504

Protocol statuses: 400, 413, 415

Request (application/json, or multipart/form-data for image input)

• prompt:string · required
• n:integer · optional · An integer from 1 through 4; imageToImage contracts require n=1.
• size:string · optional · For imageToImage contracts, only 256*256, 1024*1024 (default), or 1536*1536 are accepted; no normalization. Other models: format "W*H" with 768–2048 pixels per side; out-of-range or malformed values silently become 1024*1024. Kling image converts it to the nearest of 16:9/9:16/1:1 and the provider decides the pixels; Seedream 5.0 ignores it. See each model note in the catalog.
• model:string · optional · An explicit unknown id returns HTTP 400 invalid_model with availableModels. The Spicy Seedream models (adult content allowed; each is listed in GET /v1/models only while it is on sale) make one image per request (n=1): bytedance/seedream-5.0-pro-spicy (6 points, 1.5K) and bytedance/seedream-5.0-lite-spicy (4 points, 2K) from text alone or text plus reference images, bytedance/seedream-5.0-flash-spicy (3 points, 2K) from text only. Minors and non-consensual content are not allowed. Retention is not guaranteed; download the image as soon as you get it.
• width:integer · optional
• height:integer · optional
• seed:integer · optional
• async:boolean · optional · Seedream 5.0 pro and flash (volcengine/doubao-seedream-5.0-pro, volcengine/doubao-seedream-5.0-flash) and the Spicy Seedream models (bytedance/seedream-5.0-pro-spicy, bytedance/seedream-5.0-lite-spicy, bytedance/seedream-5.0-flash-spicy) only; other models ignore it. true returns HTTP 202 {taskId, model, status:"pending"} at once; poll POST /v1/media/task/status with that taskId every 5 seconds or slower until status is succeeded or failed. Points are held at acceptance and captured only when the poll returns the images. A failed run, a result not collected within about 55 minutes, or one lost to a server restart ends as failed; held points are released where possible, and a case that cannot be confirmed stays held for reconciliation. The returned image URLs last one hour. false or omitted keeps the synchronous 200 response, which can be cut off at the network edge with HTTP 524 when a generation takes longer than about two minutes. A content-review refusal on a Spicy Seedream model ends as failed with code provider_content_flagged. tt-web keys always use async. In multipart send the text true or false; any other value returns 400 invalid_async.
• image:file · optional · Image input, multipart only for this field. qwen-image-edit-spicy requires it as the primary image (PNG, JPEG or WebP, up to 10 MiB). Models with an imageToImage catalog contract take exactly one PNG up to 10 MiB. Seedream 5.0 pro and flash, and the Spicy Seedream pro and lite, take reference images only (referenceImage), never image. Text-to-image models refuse it. Caller URLs are never accepted.
• referenceImage:file · optional · Optional reference images; repeat the multipart field, up to 10 MiB each and 40 MiB combined (413 reference_images_too_large). qwen-image-edit-spicy: up to 2 (reference images 2 and 3, in order), PNG, JPEG or WebP. Seedream 5.0 pro: 1 to 3; Seedream 5.0 flash: 1 to 10; bytedance/seedream-5.0-pro-spicy: 1 to 3 and bytedance/seedream-5.0-lite-spicy: 1 to 10; JPEG, PNG, WebP or AVIF, each side at least 15 px, at most 36,000,000 pixels per image, aspect ratio within 1:16 to 16:1; points are the same with or without reference images. GET /v1/me/model-catalog lists referenceImageUpload with the limit for each image model that takes them; other models return 400 invalid_image_upload.
• imageBase64:string · optional · qwen-image-edit-spicy only: the primary image as Base64 in a JSON request, instead of the multipart field image. Other models return 400 unsupported_image_input.
• imageMimeType:string · optional · qwen-image-edit-spicy only: the media type of imageBase64 (image/png, image/jpeg or image/webp); defaults to image/png.
• referenceImagesBase64:string[] · optional · Reference images as Base64 in a JSON request, in order: qwen-image-edit-spicy up to 2, Seedream 5.0 pro up to 3, Seedream 5.0 flash up to 10, Spicy Seedream pro up to 3 and lite up to 10, same limits as referenceImage. A JSON body is limited to 1 MiB in total, so send larger images as multipart referenceImage. Models without reference images return 400 unsupported_image_input.
• referenceImageMimeTypes:string[] · optional · Media types for referenceImagesBase64 (qwen-image-edit-spicy and Seedream 5.0), same length and order; each defaults to image/png.
• contentAttestation:string · optional · Spicy Seedream models only. No longer required; if sent, any value is accepted and ignored.
• strength:number · optional · Only imageToImage: 0–1 (default 0.6), strength-based redraw, not precise instruction editing.
• output_format:string · optional · Only imageToImage: jpeg (default), png, or webp.

Response (application/json)

• taskId:string · optional
• model:string · required
• status:pending · optional
• images:string[] · optional
• prompt:string · optional
• size:string · optional · Echo of the normalized request value; it is not the actual output size. Read the downloaded file.
• quotaCost:integer · optional · Present on synchronous 200 responses only. 202 responses and task status do not carry it; use the catalog price.
• delivery:api_delivery_descriptor · optional · On synchronous RMW image success, an API key receives this descriptor and POSTs its JSON body to /v1/media/delivery/rmw without cookies. Browsers keep the HttpOnly-cookie image URL flow.

Errors: 400 · native · Request or schema validation failed. · Contract semantics: invalid request

Errors: 401 · native · The credential is invalid or expired. · Contract semantics: invalid or expired API key

Errors: 402 · native · Quota or points are insufficient. · Contract semantics: insufficient media points · Identifier: error=insufficient_points

Errors: 403 · native · The model or entitlement was rejected. · Contract semantics: model or entitlement rejected

Errors: 429 · native · A rate or plan limit was reached. · Contract semantics: daily or batch limit reached

Errors: 500 · native · Batch creation failed. · Contract semantics: batch creation failed

Errors: 502 · native · Upstream generation, delivery, or settlement failed. · Contract semantics: provider request, delivery, or settlement failed

Errors: 503 · native · The service is not configured or unavailable. · Contract semantics: generation service or delivery signing unavailable

Errors: 504 · native · Upstream generation timed out. · Contract semantics: provider request timed out

Errors: 400 · native · Request or schema validation failed. · Contract semantics: explicit model id is unknown · Identifier: error=invalid_model

Errors: 400 · native · Request or schema validation failed. · Contract semantics: n is not an integer from 1 through 4 · Identifier: error=invalid_n

Errors: 400 · native · Request or schema validation failed. · Contract semantics: async is sent to Seedream 5.0 pro or flash or a Spicy Seedream model with a value other than true or false · Identifier: error=invalid_async

Errors: 400 · native · Request or schema validation failed. · Contract semantics: image input (or referenceImagesBase64) was sent to a model that does not take it, or image_url was sent (never accepted) · Identifier: error=unsupported_image_input

Errors: 400 · native · Request or schema validation failed. · Contract semantics: qwen-image-edit-spicy needs a primary image (multipart image or imageBase64) · Identifier: error=image_required

Errors: 400 · native · Request or schema validation failed. · Contract semantics: more reference images than the model allows (qwen-image-edit-spicy 2, Seedream 5.0 pro 3, Seedream 5.0 flash 10, Spicy Seedream pro 3, lite 10), referenceImageMimeTypes does not match referenceImagesBase64, or a Seedream 5.0 reference image is outside its pixel limits · Identifier: error=invalid_reference_images

Errors: 400 · native · Request or schema validation failed. · Contract semantics: the multipart upload has an unexpected field, type or count for the chosen model · Identifier: error=invalid_image_upload

Errors: 413 · native · The body or image is too large. · Contract semantics: reference images exceed 40 MiB combined · Identifier: error=reference_images_too_large

Errors: 422 · native · The model refused this input (content review or limits); change the input before resubmitting. · Contract semantics: the model refused the request input, so no task was created; reason is input_moderation (content review refused the prompt, an image or a video), input_invalid (a parameter, image or video does not meet the model limits) or input_policy (the prompt asks for content the model does not generate, such as minors or non-consensual content; refused before any points are held). Change the input before submitting again; the same input will be refused again · Identifier: error=input_rejected

Errors: 502 · native · Upstream generation, delivery, or settlement failed. · Contract semantics: the image was generated but could not be stored for TokenTable delivery; held points are refunded where possible · Identifier: error=image_delivery_failed

Errors: 502 · native · Upstream generation, delivery, or settlement failed. · Contract semantics: generation failed; the response never carries the upstream message, and held points are refunded where possible · Identifier: error=image_generation_failed

Errors: 502 · native · Upstream generation, delivery, or settlement failed. · Contract semantics: the refund of held points could not be confirmed; the points stay held for reconciliation · Identifier: error=settlement_pending

POST /v1/media/video

nativeVideo · asynchronous · bearer · Availability: public

HTTP statuses: 200, 400, 401, 402, 403, 408, 413, 415, 422, 429, 502, 503

Protocol statuses: 400, 413, 415

Request (application/json or multipart/form-data)

• prompt:string · required
• size:string · optional · T2V aspect selector for wan2.6-t2v, happyhorse-1.1-t2v and Kling video: 1920*1080 (16:9), 1080*1920 (9:16) or 1440*1440 (1:1). Other "W*H" values become 1920*1080 or 1080*1920 by orientation; square-but-not-1440, malformed or missing values become 1920*1080 without an error. Seedance and w3.0-video ignore it (see each model note).
• duration:integer · optional
• resolution:480p|720p|1080p|4k · optional · Customer-selectable only for models whose catalog pricing publishes a resolutions allow-list. w3.0-video takes 720p or 1080p and w3.0-video-pro takes 1080p or 2k (lowercase; 1080p when omitted); other values answer 400 unsupported_resolution before any points are held.
• model:string · optional · Optional model id from GET /v1/models. The Spicy Seedance models (adult content allowed; each is listed only while it is on sale) make a text-to-video, or a first-frame video when image is sent, at 4-15 seconds: bytedance/seedance-2.5-spicy at 480p, 720p or 1080p; bytedance/seedance-2.0-spicy, bytedance/seedance-2.0-fast-spicy and bytedance/seedance-2.0-mini-spicy at 480p or 720p. Text-to-video is 16:9 and a first-frame video follows the image's aspect ratio. Points for 5, 10 and 15 seconds: 2.5 Spicy 59, 117 and 174 at 480p, 132, 262 and 392 at 720p, 323, 643 and 963 at 1080p; 2.0 Spicy 40, 80 and 119 at 480p, 86, 171 and 256 at 720p; 2.0 fast Spicy 32, 64 and 96 at 480p, 69, 137 and 205 at 720p; 2.0 mini Spicy 20, 40 and 60 at 480p, 43, 86 and 128 at 720p. Minors and non-consensual content are not allowed. Retention is not guaranteed; download the video as soon as you get it. While their extended sale is open, the four Spicy Seedance models also take: image plus lastImage (first and last frame, I2V_LAST); reference files (R2V: up to 9 referenceImage, up to 3 referenceVideo and up to 3 referenceAudio); one video with videoMode reference, edit or extend; and bytedance/seedance-2.5-spicy makes text-to-video and first-frame videos up to 30 seconds (points for 20 and 30 seconds: 232 and 348 at 480p, 522 and 782 at 720p, 1283 and 1922 at 1080p). Durations are 4-30 seconds on 2.5 Spicy and 4-15 seconds on the 2.0 series. An operation that is not open answers 400 image_to_video_unavailable, reference_images_unavailable or video_to_video_unavailable before any points are held. Reference images, videos and first frames that show a real person may be refused by the model's content review (422 input_rejected; held points are released where possible).
• generateAudio:boolean · optional · Spicy Seedance models only (bytedance/seedance-2.5-spicy, bytedance/seedance-2.0-spicy, bytedance/seedance-2.0-fast-spicy, bytedance/seedance-2.0-mini-spicy); other models answer 400 unexpected_field. Default true: the video has sound. Send false for a silent video; the price is the same. Sound occasionally makes a generation fail; if that happens, submit again with generateAudio false.
• contentAttestation:string · optional · Spicy Seedance models only (the four ids above). No longer required; if sent, any value is accepted and ignored.
• operation:T2V|I2V|I2V_LAST|R2V|V2V_EDIT|V2V_EXTEND · optional · Optional explicit generation mode for Seedance 2.5 and the 2.0 series (2.0, 2.0-fast, 2.0-mini), plus w3.0-video and w3.0-video-pro for T2V, I2V and R2V. R2V reference images on the 2.0 series are available to your account only when GET /v1/me/model-catalog lists R2V with referenceImageUpload for that model; otherwise R2V is not available on it. It must match the inputs: T2V = prompt only; I2V = image; I2V_LAST = image plus lastImage (first and last frame); R2V = referenceImage files (1 to 9 on Seedance; 1 to 10 on w3.0-video and w3.0-video-pro) and no image, lastImage or video; V2V_EDIT = one source video (on Seedance it equals videoMode edit); V2V_EXTEND = one source video on Seedance, equal to videoMode extend. A mismatch, or an operation that contradicts videoMode, returns 400 operation_mismatch. Omit it to let the inputs choose the mode. I2V_LAST is listed for Seedance 2.5 and, together with R2V, for the Seedance 2.0 series (2.0, 2.0-fast, 2.0-mini); it costs the same points as T2V at the same resolution and duration, and sending image plus lastImage with operation omitted is equivalent. Do not send I2V with a lastImage. On the Spicy Seedance models, while their extended sale is open, all six operations are accepted and must match the inputs the same way; R2V there also takes referenceVideo and referenceAudio, and V2V_EDIT or V2V_EXTEND is one video with videoMode edit or extend. On w3.0-video and w3.0-video-pro, R2V can also take referenceVideo and referenceAudio; these two models accept no source video.
• image:binary · optional · Optional multipart start image. The file name extension must match its real format and declared type (for example a JPEG must not be named .png), otherwise 415 image_type_mismatch with no charge.
• imageBase64:string · optional · Optional legacy JSON start image.
• imageMimeType:string · optional · MIME type for imageBase64.
• lastImage:binary · optional · Optional multipart last image; requires image.
• lastImageBase64:string · optional · Optional legacy JSON last image; requires imageBase64.
• lastImageMimeType:string · optional · MIME type for lastImageBase64.
• video:binary · optional · Optional multipart video input; mutually exclusive with image and lastImage. On Seedance models it is the source video for videoMode: MP4 or MOV, up to 50 MiB, 24–60 fps, 300–6000 px per side, 2–30 s on volcengine/doubao-seedance-2.5 and 2–15 s on the 2.0 series. On the Spicy Seedance models the limits are listed under videoMode.
• videoMode:reference|edit|extend · optional · Seedance models only, with video (or videoBase64). reference (default, all four models): a new 16:9 clip of the requested duration guided by the source video. edit (volcengine/doubao-seedance-2.5): edits the source video; the output keeps its length (4–30 s), so duration must be omitted or equal. extend (volcengine/doubao-seedance-2.5): continues the source video by duration seconds; the result contains only the added part. edit and extend keep the source aspect ratio (9:16 to 21:9). 480p, 720p or 1080p. Points are quoted before the charge from billed seconds = max(source seconds + output seconds, output seconds + ceil(output seconds × 2 / 3)). Spicy Seedance models (bytedance/seedance-2.5-spicy, bytedance/seedance-2.0-spicy, bytedance/seedance-2.0-fast-spicy, bytedance/seedance-2.0-mini-spicy), while their extended sale is open: all three modes on all four models. reference makes a 16:9 clip of the requested duration; edit on 2.5 Spicy keeps the source length (4-30 s source), and on the 2.0 series makes a 16:9 clip of the requested duration; extend continues the source video for duration seconds. 2.5 Spicy edit and extend keep the source aspect ratio (9:16 to 21:9). Their source clips are MP4 or MOV, 2-15 s (4-30 s for a 2.5 Spicy edit), 300-6000 px per side, width/height 0.4-2.5, 24-60 fps; a source clip that shows a real person may be refused by the model's content review (422 input_rejected; held points are released where possible). Points use the same billed seconds; send quoteOnly true to see them first.
• quoteOnly:boolean · optional · Seedance source-video requests, and w3.0-video and w3.0-video-pro requests. true runs every pre-charge check on the uploaded video and returns the exact quotaCost with inputSeconds and billedSeconds; nothing is charged, no task is created, and the response carries quoteOnly: true without taskId, status or prompt. On w3.0-video and w3.0-video-pro it also works without a video: inputSeconds is the measured reference video length (0 without one, possibly fractional), billedSeconds can carry milliseconds, and the response also carries model, operation, resolution and duration.
• referenceImage:binary · optional · Optional multipart reference image. Repeat for up to 9 images on Seedance, or up to 10 on w3.0-video and w3.0-video-pro (10 MiB each, 40 MiB combined). Seedance images remain 300–6000 px per side with width/height ratio 0.4–2.5. Mutually exclusive with image and lastImage; Seedance also excludes video, draft and draftTaskId. This is reference mode, not source-video extension. On the Spicy Seedance models, and on w3.0-video and w3.0-video-pro, reference images can be combined with referenceVideo and referenceAudio in one R2V request; reference images that show a real person may be refused by the model's content review (422 input_rejected; held points are released where possible).
• referenceImagesBase64:array · optional · Optional legacy JSON reference images: 1 to 9 Base64 strings on Seedance, or 1 to 10 on w3.0-video and w3.0-video-pro; same limits as referenceImage.
• referenceImageMimeTypes:array · optional · MIME types for referenceImagesBase64, same length and order.
• referenceVideo:binary · optional · Spicy Seedance models, w3.0-video and w3.0-video-pro only, multipart only. Optional reference clip for R2V. On the Spicy Seedance models repeat for up to 3 clips: MP4 or MOV, 2-15 seconds each and 15 seconds in total, up to 50 MiB each, with the source-video limits listed under videoMode (reference clips and audio together up to 60 MiB, otherwise 413 reference_media_too_large). Points are quoted on the clips' total seconds plus the output seconds; send quoteOnly true to get the exact points first. On w3.0-video and w3.0-video-pro repeat for up to 5 clips: MP4 or MOV, 1-15 seconds each and 15 seconds in total, 240-4096 px per side with width/height between 1:8 and 8:1 and no frame-rate rule, reference clips and audio together up to 60 MiB (413 reference_media_too_large); reference video seconds plus output seconds must not exceed 30 (422 video_duration_not_supported), a clip whose length cannot be measured returns 422 video_decode_failed or video_container_not_supported, and points follow the measured clip seconds plus the output seconds, rounded up to the millisecond. Other models answer 400 unexpected_file_field.
• referenceAudio:binary · optional · Spicy Seedance models, w3.0-video and w3.0-video-pro only, multipart only. Optional reference audio for R2V: MP3 or WAV, up to 15 MB each (413 audio_too_large, 415 audio_type_not_supported). On the Spicy Seedance models repeat for up to 3 files of 2-15 seconds each and 15 seconds in total; on w3.0-video and w3.0-video-pro repeat for up to 5 files of 1-15 seconds each and 15 seconds in total, measured from the file itself (a WAV file must be plain PCM or float, otherwise 422 audio_decode_failed; a length out of range returns 422 audio_duration_not_supported). It must come with at least one referenceImage or referenceVideo (400 reference_audio_requires_image_or_video) and does not change the points. Other models answer 400 unexpected_file_field.
• draft:boolean · optional · volcengine/doubao-seedance-2.5 only. true generates a 480p text-to-video draft at the 480p price; the returned taskId can then be sent as draftTaskId. Mutually exclusive with every image or video input.
• draftTaskId:string · optional · volcengine/doubao-seedance-2.5 only. taskId of a succeeded draft created by the same account within seven days; produces the 1080p final at the 1080p price for the draft duration. The draft prompt and duration are reused, so prompt may be omitted and duration must be omitted or equal. One final per draft (409 draft_already_finalised while a final is in progress or delivered).

Response (application/json)

• taskId:string · required · Keep it: there is no webhook, cancellation, idempotency key or task-list endpoint, and video has no seed. If the submission itself times out without a taskId, the API cannot confirm whether a task was created; contact support before resubmitting.
• status:string · required · An accepted request returns HTTP 200 (not 202) with status "pending".
• prompt:string · required
• model:string · required
• size:string · optional · Echo of the request; it is not the actual output width and height (for example a 9:16 start image on Seedance echoes 864*496 for a 496×864 clip). Read the downloaded file.
• duration:integer · optional
• quotaCost:integer · required
• resolution:string · optional
• draft:boolean · optional
• draftTaskId:string · optional
• videoMode:string · optional
• inputSeconds:integer · optional
• billedSeconds:integer · optional
• operation:string · optional · Spicy Seedance models only: the generation mode (I2V_LAST, R2V, V2V_EDIT or V2V_EXTEND) when it is neither T2V nor I2V.
• quoteOnly:boolean · optional

Errors: 400 · native · Request or schema validation failed. · Contract semantics: invalid request

Errors: 401 · native · The credential is invalid or expired. · Contract semantics: invalid or expired API key

Errors: 402 · native · Quota or points are insufficient. · Contract semantics: insufficient media points · Identifier: error=insufficient_points

Errors: 403 · native · The model or entitlement was rejected. · Contract semantics: model or entitlement rejected

Errors: 408 · native · The upload timed out. · Contract semantics: start-image upload timed out · Identifier: error=upload_timeout

Errors: 413 · native · The body or image is too large. · Contract semantics: start image exceeds the configured limit · Identifier: error=image_too_large

Errors: 429 · native · A rate or plan limit was reached. · Contract semantics: daily or batch limit reached

Errors: 502 · native · Upstream generation, delivery, or settlement failed. · Contract semantics: provider request, delivery, or settlement failed

Errors: 503 · native · The service is not configured or unavailable. · Contract semantics: generation service or delivery signing unavailable

Errors: 422 · native · The model refused this input (content review or limits); change the input before resubmitting. · Contract semantics: the model refused the request input, so no task was created; reason is input_moderation (content review refused the prompt, an image or a video), input_invalid (a parameter, image or video does not meet the model limits) or input_policy (the prompt asks for content the model does not generate, such as minors or non-consensual content; refused before any points are held). Change the input before submitting again; the same input will be refused again · Identifier: error=input_rejected

Errors: 400 · native · Request or schema validation failed. · Contract semantics: active model request has missing or out-of-range parameters · Identifier: error=invalid_request

Errors: 400 · native · Request or schema validation failed. · Contract semantics: explicit model id is unknown · Identifier: error=invalid_model

Errors: 400 · native · Request or schema validation failed. · Contract semantics: generateAudio must be true or false · Identifier: error=invalid_generate_audio

Errors: 400 · native · Request or schema validation failed. · Contract semantics: Spicy Seedance reference audio was sent without a reference image or reference video · Identifier: error=reference_audio_requires_image_or_video

Errors: 413 · native · The body or image is too large. · Contract semantics: Spicy Seedance reference videos and audio exceed 60 MiB combined · Identifier: error=reference_media_too_large

Errors: 413 · native · The body or image is too large. · Contract semantics: a Spicy Seedance reference audio file exceeds 15 MB · Identifier: error=audio_too_large

Errors: 415 · native · The media type is unsupported. · Contract semantics: Spicy Seedance reference audio is not MP3 or WAV · Identifier: error=audio_type_not_supported

Errors: 422 · native · The model refused this input (content review or limits); change the input before resubmitting. · Contract semantics: a w3.0-video or w3.0-video-pro reference audio file cannot be measured, so nothing is quoted or held: a WAV must be plain PCM or float in one data chunk (LIST/INFO metadata is fine; segmented wavl audio, other LIST types and truncated or padding-less chunks are refused) and an MP3 must be readable MPEG Layer III frames · Identifier: error=audio_decode_failed

Errors: 400 · native · Request or schema validation failed. · Contract semantics: resolution is not offered by the chosen w3.0 model (w3.0-video: 720p or 1080p; w3.0-video-pro: 1080p or 2k) · Identifier: error=unsupported_resolution

Errors: 400 · native · Request or schema validation failed. · Contract semantics: a form field the chosen model does not accept: an unknown multipart text field, a field that only some Seedance models take sent to another model, or reference video or audio fields sent to w3.0-video or w3.0-video-pro in a JSON body (those files are multipart only) · Identifier: error=unexpected_field

Errors: 400 · native · Request or schema validation failed. · Contract semantics: more files than the model accepts: more reference images, reference videos or reference audio files than its limit (w3.0-video and w3.0-video-pro: up to 5 reference videos and 5 reference audio files), or more files than one start image plus one last image · Identifier: error=too_many_files

Errors: 400 · native · Request or schema validation failed. · Contract semantics: the inputs ask for a different operation: operation does not match the files sent, or on w3.0-video and w3.0-video-pro image or lastImage is combined with reference files, or a source video or videoMode is sent (these models take reference files instead) · Identifier: error=operation_mismatch

Errors: 413 · native · The body or image is too large. · Contract semantics: a video file exceeds its limit: 100 MB per w3.0-video or w3.0-video-pro reference video, 50 MiB per multipart video or reference video for other models, or 20 MiB decoded for videoBase64 · Identifier: error=video_too_large

Errors: 415 · native · The media type is unsupported. · Contract semantics: a source or reference video is not MP4 or MOV · Identifier: error=video_type_not_supported

Errors: 422 · native · The model refused this input (content review or limits); change the input before resubmitting. · Contract semantics: a source or reference video is empty or cannot be decoded as an MP4 or MOV file with a video stream · Identifier: error=video_decode_failed

Errors: 422 · native · The model refused this input (content review or limits); change the input before resubmitting. · Contract semantics: a source or reference video is readable but its container cannot be measured: send a plain MP4 or MOV with exactly one video track, no fragments and no multi-part edit list (re-export it and try again); for a video edit the container must also match the declared MP4 or MOV type · Identifier: error=video_container_not_supported

Errors: 422 · native · The model refused this input (content review or limits); change the input before resubmitting. · Contract semantics: a source or reference video is outside the model's size limits (side length, aspect ratio or total pixels); w3.0-video and w3.0-video-pro take a shorter side of at least 240 px, a longer side of at most 4096 px and an aspect ratio of at most 8:1 · Identifier: error=video_dimensions_not_supported

Errors: 422 · native · The model refused this input (content review or limits); change the input before resubmitting. · Contract semantics: a source or reference video is outside the model's duration limits, or reference videos are too long together; w3.0-video and w3.0-video-pro take 1 to 15 seconds per reference video, at most 15 seconds in total, and reference video seconds plus output seconds of at most 30 · Identifier: error=video_duration_not_supported

Errors: 422 · native · The model refused this input (content review or limits); change the input before resubmitting. · Contract semantics: a w3.0-video or w3.0-video-pro reference audio file is shorter than 1 second or longer than 15 seconds, or the reference audio files are longer than 15 seconds together · Identifier: error=audio_duration_not_supported

Errors: 403 · native · The model or entitlement was rejected. · Contract semantics: Starter video generation requires purchased points before dispatch · Identifier: code=video_generation_requires_payment

Errors: 503 · native · The service is not configured or unavailable. · Contract semantics: generation is temporarily unavailable; no task was created, and held points are released where possible · Identifier: error=provider_payment_required

Errors: 502 · native · Upstream generation, delivery, or settlement failed. · Contract semantics: video generation failed; the response never carries the upstream message · Identifier: error=video_generation_failed

POST /v1/media/audio

nativeAudio · synchronous · bearer · Availability: public

HTTP statuses: 200, 400, 401, 402, 403, 413, 415, 502, 503

Protocol statuses: 400, 413, 415

Request (application/json)

• text:string · required · Up to 2000 characters per call; longer text returns 400 text_too_long, so split it.
• voice:string · optional · longxiaochun_v2 (default), longcheng_v2, longhua_v2 or longshu_v2; any other or missing value uses the default without an error.
• model:string · optional

Response (application/json)

• audioUrl:string · required · Always a TokenTable GET /v1/media/blob/:id URL, held in server memory for one hour and lost on a server restart; points are charged only after the audio is stored. Download it immediately.
• model:string · required
• voice:string · required
• characters:integer · required
• quotaCost:integer · required

Errors: 400 · native · Request or schema validation failed. · Contract semantics: invalid request

Errors: 401 · native · The credential is invalid or expired. · Contract semantics: invalid or expired API key

Errors: 402 · native · Quota or points are insufficient. · Contract semantics: insufficient media points · Identifier: error=insufficient_points

Errors: 403 · native · The model or entitlement was rejected. · Contract semantics: model or entitlement rejected

Errors: 502 · native · Upstream generation, delivery, or settlement failed. · Contract semantics: provider request, delivery, or settlement failed

Errors: 503 · native · The service is not configured or unavailable. · Contract semantics: generation service or delivery signing unavailable

Errors: 502 · native · Upstream generation, delivery, or settlement failed. · Contract semantics: the audio was generated but could not be stored for TokenTable delivery; held points are refunded where possible · Identifier: error=audio_delivery_failed

Errors: 502 · native · Upstream generation, delivery, or settlement failed. · Contract semantics: generation failed; the response never carries the upstream message, and held points are refunded where possible · Identifier: error=audio_generation_failed

Errors: 502 · native · Upstream generation, delivery, or settlement failed. · Contract semantics: the refund of held points could not be confirmed; the points stay held for reconciliation · Identifier: error=settlement_pending

POST /v1/media/video/batch

videoBatch · asynchronous · bearer · Availability: public

HTTP statuses: 202, 400, 401, 402, 403, 413, 415, 429, 500, 503

Protocol statuses: 400, 413, 415

Request (application/json)

• items:video_request[] · required · 1 to 30 items. Each item uses only prompt (required), model, size and duration. Batch runs text-to-video only: if the request body or any item carries a non-null imageBase64, lastImageBase64, videoBase64, referenceImagesBase64, image, lastImage, referenceImage, video, image_url, imageUrl or referenceImages, the whole batch is rejected with 400 unsupported_media_input (the message names the first offending field, such as items[0].imageBase64, with a zero-based index), so send image-to-video, first/last-frame, reference-image or source-video jobs one at a time to POST /v1/media/video. Batch-capable models: wan2.6-t2v, kling/kling-v3-omni-video-generation and happyhorse-1.1-t2v. Any advanced model rejects the whole batch with 403 (media_tier_not_entitled, or media_tier_batch_unsupported when activated); volcengine/doubao-seedance-* models return 400 operation_not_supported; an unknown model id returns 400 invalid_model with availableModels. None of these refusals charges points or creates a batch.
• size:string · optional · Batch-level default for items without size (default 1920*1080). 1920*1080, 1080*1920 and 1440*1440 are kept; any other W*H becomes 1920*1080 if landscape or 1080*1920 if portrait instead of being rejected. The echoed size is not a measured output size.
• duration:integer · optional · Batch-level default seconds for items without duration (default 5). wan2.6-t2v accepts whole 2–15 seconds, the other batch models 3–15; any other value returns 400 unsupported_duration. Points are summed per item, and insufficient points return 402 insufficient_points.
• model:string · optional · Batch-level default model for items without model. An item value takes precedence over this, and this over the default model.

Response (application/json)

• batchId:string · required
• status:string · required
• totalItems:integer · required
• quotaCost:integer · required
• items:batch_item[] · required

Errors: 400 · native · Request or schema validation failed. · Contract semantics: invalid request

Errors: 401 · native · The credential is invalid or expired. · Contract semantics: invalid or expired API key

Errors: 402 · native · Quota or points are insufficient. · Contract semantics: insufficient media points · Identifier: error=insufficient_points

Errors: 403 · native · The model or entitlement was rejected. · Contract semantics: model or entitlement rejected

Errors: 429 · native · A rate or plan limit was reached. · Contract semantics: daily or batch limit reached

Errors: 500 · native · Batch creation failed. · Contract semantics: batch creation failed

Errors: 503 · native · The service is not configured or unavailable. · Contract semantics: generation service or delivery signing unavailable

Errors: 400 · native · Request or schema validation failed. · Contract semantics: batch is text-to-video only; an image or video input field in the body or any item rejects the whole batch · Identifier: error=unsupported_media_input

Errors: 403 · native · The model or entitlement was rejected. · Contract semantics: Starter video generation requires purchased points before dispatch · Identifier: code=video_generation_requires_payment

GET /v1/media/batch/:batchId

batchStatus · synchronous · bearer · Availability: public

HTTP statuses: 200, 400, 401, 404, 429, 503

Request (application/json)

• batchId:string · required · Path parameter.

Response (application/json)

• batchId:string · required
• status:string · required
• totalItems:integer · required
• completedItems:integer · required
• failedItems:integer · required
• quotaCost:integer · required
• createdAt:string · required
• updatedAt:string · required
• items:batch_item[] · required · Each item carries videoUrl as a TokenTable delivery reference and, for API keys, a delivery descriptor. error is video_generation_failed, video_delivery_unavailable, settlement_pending or generation_pending, never an upstream message.

Errors: 400 · fastify · Request or schema validation failed. · Contract semantics: request schema validation failed

Errors: 401 · native · The credential is invalid or expired. · Contract semantics: invalid or expired API key

Errors: 404 · native · The owned resource was not found. · Contract semantics: owned resource not found

Errors: 429 · native · A rate or plan limit was reached. · Contract semantics: daily or batch limit reached

Errors: 503 · native · The service is not configured or unavailable. · Contract semantics: at least one item could not get a TokenTable delivery reference; the whole response is returned with HTTP 503 · Identifier: items[].error=video_delivery_unavailable

POST /v1/media/task/status

taskStatus · synchronous · bearer · Availability: public

HTTP statuses: 200, 400, 401, 404, 410, 413, 415, 429, 502, 503

Protocol statuses: 400, 413, 415

Request (application/json)

• taskId:string · required · Poll every 5 seconds or slower. Status, Seedance artifact and batch-status calls share a global limit of 200 requests per minute per client IP (x-ratelimit-limit); media submissions are not counted by it, and Starter plans have daily caps.
• model:string · optional

Response (application/json)

• status:pending|succeeded|failed|delivery_failed · required
• generationStatus:succeeded · optional · Present with delivery_failed to distinguish successful billed generation from failed delivery.
• videoUrl:string · optional
• images:string[] · optional · Image tasks only, and always TokenTable URLs; video tasks return an empty array and use videoUrl and delivery instead.
• delivery:api_delivery_descriptor · optional · Present only for tt-live API keys after video generation succeeds. Follow its method and path with the same Authorization header.
• error:error · optional · Seedance reports every terminal failure after the task was created, including content review, as "provider failed" without a code; held points are released where possible, and a case that cannot be confirmed stays held for reconciliation. "artifact_too_large" means the finished clip exceeded the durable store limit; it is not delivered or captured.
• code:provider_generation_failed|provider_content_flagged|delivery_secret_unavailable|delivery_origin_unapproved|delivery_token_roundtrip_failed|delivery_token_unavailable|durable_transfer_failed · optional · Safe diagnostic code for a provider-terminal or fail-closed delivery failure; never contains an upstream URL, token, task ID, payload, or key.

Errors: 401 · native · The credential is invalid or expired. · Contract semantics: invalid or expired API key

Errors: 404 · native · The owned resource was not found. · Contract semantics: owned resource not found

Errors: 502 · native · Upstream generation, delivery, or settlement failed. · Contract semantics: provider request, delivery, or settlement failed

Errors: 503 · native · The service is not configured or unavailable. · Contract semantics: generation service or delivery signing unavailable

Errors: 410 · native · The legacy endpoint is disabled. · Contract semantics: a Seedream 5.0 or Spicy Seedream async image was already delivered and its one-hour result has expired; it is not generated again · Identifier: error=image_result_expired

GET /v1/media/image-artifact/:taskId

imageArtifactDelivery · streaming · bearer · Availability: public

HTTP statuses: 200, 400, 401, 404, 410, 429, 503

Request (application/json)

• taskId:string · required · Path parameter of an owned captured I2I image task.

Response (image/jpeg, image/png or image/webp)

• image bytes:binary · required

Errors: 400 · fastify · Request or schema validation failed. · Contract semantics: request schema validation failed

Errors: 401 · native · The credential is invalid or expired. · Contract semantics: invalid or expired API key

Errors: 404 · native · The owned resource was not found. · Contract semantics: owned resource not found

Errors: 429 · native · A rate or plan limit was reached. · Contract semantics: daily or batch limit reached

Errors: 503 · native · The service is not configured or unavailable. · Contract semantics: generation service or delivery signing unavailable

Errors: 410 · native · The legacy endpoint is disabled. · Contract semantics: private image retention expired

Security and data handling: Requester and quota-owner task ownership, captured ledger state, independent image namespace, retention and SHA-256 are checked. Provider URLs are never returned; private image retention is P7D. This endpoint does not activate any candidate model.

GET /v1/media/artifact/:taskId

seedanceArtifactDelivery · streaming · bearer · Availability: public

HTTP statuses: 200, 206, 400, 401, 404, 416, 429, 503

Request (application/json)

• taskId:string · required · Owned task path parameter. Seedance artifacts are kept for 30 days after transfer.
• Range:header:bytes=start-end|bytes=start-|bytes=-suffix · optional · Optional single byte range.

Response (stored video media type)

• video bytes:binary · required

Errors: 400 · fastify · Request or schema validation failed. · Contract semantics: request schema validation failed

Errors: 401 · native · The credential is invalid or expired. · Contract semantics: invalid or expired API key

Errors: 404 · native · The owned resource was not found. · Contract semantics: owned resource not found

Errors: 429 · native · A rate or plan limit was reached. · Contract semantics: daily or batch limit reached

Errors: 503 · native · The service is not configured or unavailable. · Contract semantics: generation service or delivery signing unavailable

Errors: 416 · native · Handle this error according to the contract. · Contract semantics: requested byte range is not satisfiable · Identifier: error=range_not_satisfiable

Security and data handling: Authorization, requester ownership, captured ledger state, private object reference, byte count, storage version, and SHA-256 are rechecked before delivery. Provider URLs are never returned.

POST /v1/media/delivery/video

apiVideoDelivery · streaming · bearer API key · Availability: public

HTTP statuses: 200, 206, 400, 401, 404, 410, 413, 415, 416, 429, 502

Protocol statuses: 400, 413, 415

Request (application/json)

• taskId:string · required
• grant:string · required · Opaque encrypted grant returned by task status; send only in this JSON body.
• Range:header:bytes=start-end|bytes=start- · optional · Optional single byte range.

Response (provider media type)

• media bytes:binary · required

Errors: 401 · native · The credential is invalid or expired. · Contract semantics: invalid or mismatched delivery grant · Identifier: code=invalid_grant

Errors: 404 · native · The owned resource was not found. · Contract semantics: owned completed task not found

Errors: 410 · native · The delivery grant or media has expired. · Contract semantics: delivery grant or upstream asset expired

Errors: 502 · native · Upstream generation, delivery, or settlement failed. · Contract semantics: upstream media is temporarily unreachable · Identifier: code=upstream_unreachable

deliveryFailureCodes: invalid_grant, token_expired, upstream_expired, upstream_unreachable

Security and data handling: The grant belongs in the request body and never in a URL, query, log, or cookie. Authorization and task ownership are rechecked before relay.

POST /v1/media/delivery/rmw

apiRmwDelivery · streaming · bearer API key · Availability: public

HTTP statuses: 200, 206, 400, 401, 404, 410, 413, 415, 416, 429, 502

Protocol statuses: 400, 413, 415

Request (application/json)

• taskId:string · required
• grant:string · required · Opaque encrypted grant returned by task status; send only in this JSON body.
• Range:header:bytes=start-end|bytes=start- · optional · Optional single byte range.

Response (provider media type)

• media bytes:binary · required

Errors: 401 · native · The credential is invalid or expired. · Contract semantics: invalid or mismatched delivery grant · Identifier: code=invalid_grant

Errors: 404 · native · The owned resource was not found. · Contract semantics: owned completed task not found

Errors: 410 · native · The delivery grant or media has expired. · Contract semantics: delivery grant or upstream asset expired

Errors: 502 · native · Upstream generation, delivery, or settlement failed. · Contract semantics: upstream media is temporarily unreachable · Identifier: code=upstream_unreachable

deliveryFailureCodes: invalid_grant, token_expired, upstream_expired, upstream_unreachable

Security and data handling: The grant belongs in the request body and never in a URL, query, log, or cookie. Authorization, task ownership, and the durable RMW delivery reference are rechecked before relay.

GET /v1/media/blob/:id

imageBlobDelivery · streaming · opaque unguessable path · Availability: public

HTTP statuses: 200, 410, 429

Request (application/json)

• id:uuid · required · Path parameter returned by a successful image generation (for example Seedream 5.0, synchronous or async). The image is held in server memory for one hour and is also lost if the server restarts, after which this returns 410 blob_expired; download it immediately.

Response (image media type)

• image bytes:binary · required

Errors: 410 · native · The delivery grant or media has expired. · Contract semantics: in-memory image delivery expired · Identifier: error=blob_expired

TTL: 3600s

GET /v1/media/img

legacyImageDelivery · disabled · none · Availability: disabled

HTTP statuses: 410, 429

Request (application/json)

• u:string · optional · Legacy query parameter from older image responses; it is ignored.

Response (application/json)

• error:string · required

Errors: 410 · native · The delivery grant or media has expired. · Contract semantics: retired legacy image URL; it never contacts an upstream service · Identifier: error=legacy_image_url_disabled

Replacement: GET /v1/media/blob/:id

Recommendation: Use only the replacement endpoint. [Image responses now return only TokenTable URLs; download from the URL in the current response and store the file yourself.]

GET /v1/media/task/:taskId

legacyTaskStatus · disabled · bearer · Availability: disabled

HTTP statuses: 400, 410

Request (application/json)

• taskId:string · required · Legacy path parameter; never use this endpoint.

Response (application/json)

• error:string · required

Errors: 400 · fastify · Request or schema validation failed. · Contract semantics: missing Authorization header

Errors: 410 · native · The legacy endpoint is disabled. · Contract semantics: legacy endpoint disabled

Authentication behavior: Use Authorization: Bearer <TOKEN>. Only the Responses and Anthropic Messages compatible endpoints listed by the manifest may use x-api-key. [Missing Authorization is rejected by schema with 400; any present string reaches the disabled handler and returns 410.]

Replacement: POST /v1/media/task/status

Recommendation: Use only the replacement endpoint. [Use only the replacement endpoint.]

Text cURL example

curl https://tokentable.asia/v1/chat/completions -H "Authorization: Bearer $TOKENTABLE_API_KEY" -H "Content-Type: application/json" -d '{"model":"auto","messages":[{"role":"user","content":"Hello"}]}'

Image Python example

BASE = "https://tokentable.asia/v1"
requests.post(BASE + "/media/image", headers=AUTH, json={"prompt":"Prompt","model":MODEL_FROM_CATALOG})

Text-to-video Node.js example

const BASE = "https://tokentable.asia/v1";
await fetch(BASE + "/media/video", {method:"POST", headers:AUTH_JSON, body:JSON.stringify({prompt:"Prompt", model, duration})})

Image-to-video multipart cURL example

curl "https://tokentable.asia/v1/media/video" -H "Authorization: Bearer $TOKENTABLE_API_KEY" -F "prompt=Prompt" -F "model=$MODEL" -F "duration=5" -F "resolution=720p" -F "image=@start.jpg"

Status polling Node.js example

const BASE = "https://tokentable.asia/v1";
await fetch(BASE + "/media/task/status", {method:"POST", headers:AUTH_JSON, body:JSON.stringify({taskId, model})})

Speech Python example

BASE = "https://tokentable.asia/v1"
requests.post(BASE + "/media/audio", headers=AUTH, json={"text":"Hello","model":MODEL_FROM_CATALOG,"voice":VOICE_FROM_CATALOG})

First and last frame (I2V_LAST) multipart cURL example: image plus lastImage; without operation the inputs choose the mode

curl "https://tokentable.asia/v1/media/video" -H "Authorization: Bearer $TOKENTABLE_API_KEY" -F "prompt=Prompt" -F "model=$MODEL" -F "duration=5" -F "image=@shot01.png;type=image/png" -F "lastImage=@shot02.png;type=image/png"

Reference images (R2V) multipart cURL example: repeat the referenceImage field, kept in submission order

curl "https://tokentable.asia/v1/media/video" -H "Authorization: Bearer $TOKENTABLE_API_KEY" -F "prompt=Prompt" -F "model=$MODEL" -F "duration=5" -F "referenceImage=@character_a.jpg;type=image/jpeg" -F "referenceImage=@character_b.jpg;type=image/jpeg"

Download cURL example: delivery.method GET (Seedance artifact)

curl -o result.mp4 "https://tokentable.asia/v1/media/artifact/$TASK_ID" -H "Authorization: Bearer $TOKENTABLE_API_KEY"

Download cURL example: delivery.method POST (/media/delivery/video or /rmw); the grant goes only in the JSON body

curl -o result.mp4 "https://tokentable.asia/v1/media/delivery/rmw" -H "Authorization: Bearer $TOKENTABLE_API_KEY" -H "Content-Type: application/json" -d '{"taskId":"TASK_ID","grant":"GRANT_FROM_STATUS_DELIVERY"}'

Spicy image with reference images, multipart cURL example: bytedance/seedream-5.0-lite-spicy, repeat referenceImage (1–10); images come back synchronously and the URL is kept for one hour, so download it at once

curl "https://tokentable.asia/v1/media/image" -H "Authorization: Bearer $TOKENTABLE_API_KEY" -F "model=bytedance/seedream-5.0-lite-spicy" -F "prompt=Prompt; keep the face from image 1 and the outfit from image 2" -F "n=1" -F "referenceImage=@character.jpg;type=image/jpeg" -F "referenceImage=@outfit.png;type=image/png"
# 200 {"images":["https://tokentable.asia/v1/media/blob/..."], ...}: download images[0] at once (kept for one hour)

Spicy text-to-video Node.js example: bytedance/seedance-2.0-mini-spicy, 480p or 720p, 4–15 seconds, fixed 16:9; generateAudio defaults to true, send false for a silent video (same points)

const BASE = "https://tokentable.asia/v1";
const res = await fetch(BASE + "/media/video", {method:"POST", headers:AUTH_JSON, body:JSON.stringify({model:"bytedance/seedance-2.0-mini-spicy", prompt:"Prompt", duration:5, resolution:"480p", generateAudio:false})});
const { taskId } = await res.json();

Spicy first-frame video multipart cURL example: image is the first frame (the video follows its aspect ratio); lastImage, referenceImage and video are not accepted

curl "https://tokentable.asia/v1/media/video" -H "Authorization: Bearer $TOKENTABLE_API_KEY" -F "model=bytedance/seedance-2.0-mini-spicy" -F "prompt=Prompt" -F "duration=5" -F "resolution=720p" -F "generateAudio=true" -F "image=@first_frame.jpg;type=image/jpeg"

Spicy video polling and download Python example: poll /media/task/status with the taskId, then GET videoUrl (/media/artifact/:taskId) with the same key once it succeeds; if a poll fails temporarily, keep polling the same taskId and do not resubmit

BASE = "https://tokentable.asia/v1"
while True:
    r = requests.post(BASE + "/media/task/status", headers=AUTH, json={"taskId": task_id})
    s = r.json() if r.ok else {"status": "pending"}  # 502 Failed to reach provider: keep polling the same taskId
    if s["status"] in ("succeeded", "failed"):
        break
    time.sleep(10)
if s["status"] == "succeeded":
    open("result.mp4", "wb").write(requests.get(s["videoUrl"], headers=AUTH).content)