Request flow
Clients only call /v1/videos on new-api. new-api and ZeroFA handle model routing, protocol conversion, upstream submission, and polling.
End-to-end flow
Client
POST https://your-new-api.example.com/v1/videos
↓
new-api (DoubaoVideo conversion)
POST https://zerofa.ai/ark/api/v3/contents/generations/tasks
↓
ZeroFA (Ark passthrough with Volcano credentials)
POST https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasksClients use a Token issued by new-api. The new-api channel uses an API Key issued by ZeroFA. Do not mix these two keys.
Configure the DoubaoVideo channel
Create a Volcano video channel in new-api, select the DoubaoVideo-compatible protocol, and use ZeroFA as its upstream.
new-api channel settings
Channel type: DoubaoVideo
Base URL: https://zerofa.ai/ark
API Key: sk-zerofa-xxx
Model: your-seedance-model-idRequired settings
DoubaoVideoChannel typeRequiredSelect DoubaoVideo so new-api converts /v1/videos requests into native Volcano Ark tasks.
https://zerofa.ai/arkBase URLRequiredEnter only the ZeroFA /ark root. Do not append /api/v3 or the full task path.
sk-zerofa-xxxAPI KeyRequiredUse an API Key issued by the ZeroFA developer console. It is used only for calls from new-api to ZeroFA.
your-seedance-model-idModelRequiredEnable the same Seedance model ID actually configured on this site in both the channel model list and the caller token permissions. Do not copy a model ID from another site.
The DoubaoVideo adapter appends /api/v3/contents/generations/tasks to the Base URL. Use this site's admin-configured public API URL with /ark appended.
① Submit through new-api
Send the request to the other party's new-api host and authenticate with a Token issued by that new-api instance. The example below is text-to-video.
Submit a video task
NEW_API_BASE="https://your-new-api.example.com"
NEW_API_KEY="sk-new-api-xxx"
curl -sS -X POST "${NEW_API_BASE}/v1/videos" \
-H "Authorization: Bearer ${NEW_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"model": "your-seedance-model-id",
"prompt": "A shiba inu running through snow with cinematic camera movement and natural, realistic visuals",
"seconds": "5",
"metadata": {
"resolution": "720p",
"ratio": "16:9",
"generate_audio": true,
"watermark": false
}
}'
# {"id":"task_xxx","task_id":"task_xxx","object":"video",
# "model":"your-seedance-model-id","status":"queued","progress":0}Body parameters
modelstringRequiredThe model name exposed by new-api. Keep the channel's upstream model mapped to the same ZeroFA model name.
Example:
your-seedance-model-idpromptstringRequiredThe video prompt. new-api converts it into the text item in the Volcano content array.
Example:
A shiba inu running through snow with cinematic camera movement and natural, realistic visualsimagestringOptionalOne reference image URL or data URI. new-api converts it into one image_url item.
Example:
https://.../reference.pngimagesstring[]OptionalAn array of reference-image URLs or data URIs. Recommended for ordinary multi-reference requests.
Example:
["https://.../a.png","https://.../b.png"]secondsstringRequiredVideo duration. With the current DoubaoVideo converter, send it as a string such as "5".
Example:
5metadata.resolutionstringOptionalOutput resolution such as 720p. DoubaoVideo reads structured Volcano parameters from metadata.
Example:
720pmetadata.ratiostringOptionalOutput aspect ratio such as 16:9.
Example:
16:9metadata.generate_audiobooleanOptionalWhether to generate audio when supported by the selected Seedance 2.0 model.
Example:
trueWith the current new-api code, send seconds as a string and place Volcano parameters such as resolution, ratio, and generate_audio under metadata so the generic /v1/videos request does not drop them.
Single image, multiple images, and roles in new-api
Use top-level image for one reference and top-level images for multiple references. new-api creates Volcano image_url items in array order, so the prompt can describe each as image 1, image 2, and so on.
Multiple references · recommended
curl -sS -X POST "${NEW_API_BASE}/v1/videos" \
-H "Authorization: Bearer ${NEW_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"model": "your-seedance-model-id",
"prompt": "Use image 1 for the character, image 2 for the outfit, and image 3 for the setting, then create a coherent cinematic shot",
"seconds": "5",
"images": [
"https://example.com/person.png",
"https://example.com/outfit.png",
"https://example.com/location.png"
],
"metadata": {
"resolution": "720p",
"ratio": "16:9",
"generate_audio": true,
"watermark": false
}
}'Only when every material must retain an explicit role, place the native Volcano content array under metadata.content. new-api preserves those image items and appends the top-level prompt as the text item.
Multiple references · preserve reference_image roles
curl -sS -X POST "${NEW_API_BASE}/v1/videos" \
-H "Authorization: Bearer ${NEW_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"model": "your-seedance-model-id",
"prompt": "Strictly follow the character, outfit, and setting in the three reference images and create a coherent shot",
"seconds": "5",
"metadata": {
"resolution": "720p",
"ratio": "16:9",
"generate_audio": true,
"content": [
{
"type": "image_url",
"image_url": {"url": "https://example.com/person.png"},
"role": "reference_image"
},
{
"type": "image_url",
"image_url": {"url": "https://example.com/outfit.png"},
"role": "reference_image"
},
{
"type": "image_url",
"image_url": {"url": "https://example.com/location.png"},
"role": "reference_image"
}
]
}
}'Do not put content at the top level of /v1/videos. It is not part of new-api's generic video request and may be ignored. metadata.content is a DoubaoVideo-specific extension and is not portable to every new-api video channel.
② Query through new-api
Use the id returned by submission and query the same new-api instance. Status is queued, in_progress, completed, or failed.
Query a video task
TASK_ID="task_xxx"
curl -sS "${NEW_API_BASE}/v1/videos/${TASK_ID}" \
-H "Authorization: Bearer ${NEW_API_KEY}"
# Running: {"id":"task_xxx","status":"in_progress","progress":50,...}
# Completed: {"id":"task_xxx","status":"completed","progress":100,
# "metadata":{"url":"https://..."},...}Use the public task_* ID returned by new-api, not an internal ZeroFA or Volcano cgt-* ID. The completed video URL is returned in metadata.url.
Request and response bodies
Use the examples below to verify the request and response structures. To send a request, select Debug at the top of the page.
① Submit through new-api
NEW_API_BASE="https://your-new-api.example.com"
NEW_API_KEY="sk-new-api-xxx"
curl -sS -X POST "${NEW_API_BASE}/v1/videos" \
-H "Authorization: Bearer ${NEW_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"model": "your-seedance-model-id",
"prompt": "A shiba inu running through snow with cinematic camera movement and natural, realistic visuals",
"seconds": "5",
"metadata": {
"resolution": "720p",
"ratio": "16:9",
"generate_audio": true,
"watermark": false
}
}'
# {"id":"task_xxx","task_id":"task_xxx","object":"video",
# "model":"your-seedance-model-id","status":"queued","progress":0}② Query through new-api
TASK_ID="task_xxx"
curl -sS "${NEW_API_BASE}/v1/videos/${TASK_ID}" \
-H "Authorization: Bearer ${NEW_API_KEY}"
# Running: {"id":"task_xxx","status":"in_progress","progress":50,...}
# Completed: {"id":"task_xxx","status":"completed","progress":100,
# "metadata":{"url":"https://..."},...}