Volcano Ark Native Image and Video API (/ark)

When to use it

The standard /v1/videos and /v1/images/generations endpoints cover common calls. Use /ark for newly released Volcano parameters, Seedance-specific controls, or native Seedream fields.

At present, /ark exposes image generation plus video task submission, query, and list endpoints. Use standard endpoints for other Volcano capabilities.

Path mapping: /ark replaces Volcano /api

The native Volcano Ark URL uses /api after the host. When calling through ZeroFA, replace that /api segment with /ark and keep the remaining /v3/contents/... path unchanged. Direct clients should use /ark/v3/....

Two URLs for the same endpoint

Volcano native  https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks
ZeroFA recommended   https://api.fornai.im/ark/v3/contents/generations/tasks

ZeroFA forwards the recommended path to Volcano /api/v3/contents/generations/tasks. The native Volcano request body, query parameters, and response format are preserved.

Connect through new-api

Create or edit the new-api channel used for Volcano video, set its custom API address (Base URL) to the ZeroFA /ark root, enter a ZeroFA API Key, and configure the Seedance models you use. new-api and ZeroFA handle the remaining routing automatically.

Open the complete new-api Volcano video setup guide →

new-api channel configuration

# Upstream settings in the new-api channel
API address / Base URL: https://api.fornai.im/ark
API Key: sk-zerofa-xxx
Model: your-seedance-model-id

Set the Base URL only through the /ark root; do not append a task path manually.

Two-step native Volcano flow

① Submit

POST /ark/v3/contents/generations/tasksNative Volcano bodyRequired

The body is the original Volcano Ark video task request with model and content. The original response is returned, including the Volcano task id. Submission is not charged.

② Poll

GET /ark/v3/contents/generations/tasks/:idid = Volcano task idRequired

The query is forwarded unchanged and returns the original Volcano response. status=succeeded includes content.video_url and triggers idempotent duration billing on the first success.

③ Task list (paginated)

GET /ark/v3/contents/generations/taskspage_num / page_size / filter.*Optional

Returns the video tasks of the current account in the Volcano list contract. id is this site's task id (interoperable with the poll endpoint). The list is a read-only database snapshot: non-terminal tasks appear as queued/running and are not refreshed against the upstream per item. Item fields mirror the query endpoint: model is this site's model name; resolution/duration/usage reflect the requested (delivery) tier; tasks with last-frame delivery return the frame image in content.last_frame_url.

page_numintegerOptional

Page number, starting at 1, default 1

page_sizeintegerOptional

Items per page, 1–100, default 10

filter.statusstringOptional

Filter by status, comma-separated: queued / running / succeeded / failed / cancelled

filter.task_idsstringOptional

Filter by task ids, comma-separated site task ids

filter.modelstringOptional

Filter by model name

filter.service_tierstringOptional

Accepted but currently does not affect filtering (this site routes at base model price)

This id is a native Volcano task id in cgt-* format. Query it through /ark/v3/.../:id. It is not interchangeable with the platform task id used by /v1/videos.

When the submission includes return_last_frame:true, the query/list response returns the last-frame image in content.last_frame_url. The link is a short-lived signed URL (about 24 hours); re-querying the task yields a fresh link. Download and retain promptly.

Draft mode

Seedance 2.5 supports two-step generation: generate a 480p preview draft to verify the result, then produce a 1080p final video from the draft id. Each step bills independently: the draft bills at 480p, the final video bills at its target resolution (1080p); the token unit price depends on whether the draft included input video. Draft task ids are valid for 7 days.

① Step 1: generate a 480p draft

# 样片模式 Step1：生成 480p 预览样片
# 顶层 draft:true + resolution 480p（仅支持 480p）
curl -X POST "https://api.fornai.im/ark/v3/contents/generations/tasks" \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-seedance-model-id",
    "content": [
      { "type": "text", "text": "一只柴犬在雪地奔跑 --ratio 16:9 --duration 5" }
    ],
    "draft": true,
    "resolution": "480p"
  }'

# → {"id":"cgt-..."}  记住这个 task id，Step2 需要用它

② Step 2: generate the 1080p final video from the draft id

# 样片模式 Step2：基于样片 ID 生成 1080p 成片
# content 只带 draft_task 引用，resolution 固定 1080p（仅支持 1080p）
curl -X POST "https://api.fornai.im/ark/v3/contents/generations/tasks" \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-seedance-model-id",
    "content": [
      { "type": "draft_task", "draft_task": { "id": "cgt-..." } }
    ],
    "resolution": "1080p"
  }'

# → 成片 resolution=1080p，其余参数（提示词/参考素材/时长/比例/seed/音频）由 Step1 自动复用

Draft mode parameters

draftbooleanOptional

Top-level draft:true enables draft mode. Only 480p is supported; any other resolution is rejected.

draft_task.idstringOptional

In Step 2, the content array carries a draft_task reference whose id is the task id from Step 1 (you may use this site's task id; the platform restores the Volcano task id automatically).

resolutionstringOptional

Step 1 is fixed at 480p and Step 2 at 1080p; any other resolution is rejected.

Step 2's content carries only the draft_task reference. Prompt, reference media, duration, ratio, seed, and audio are automatically reused from Step 1 — do not resend them (the upstream rejects them). The final video stays highly consistent with the draft in structure, framing, and motion.

Use the official Volcano schema

/ark is a native passthrough endpoint and does not redefine Volcano content items, roles, model parameters, or asset limits. When a model has a default bitrate and the request omits bitrate_mode, that default is added; all other fields retain native semantics. Use the latest official Volcano documentation for request bodies and model capabilities.

Replace the native /api segment with this site's /ark and authenticate with this site's API key. Do not infer the full provider schema from the examples here; the official Volcano documentation is authoritative when fields change.

Billing model

Successful video is settled by duration and model price; successful images are settled by actual image count. Failures release reservations, and unsettled results are not delivered.

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 native Volcano body

# Native Volcano body: content and advanced flags pass through unchanged
# Path rule: replace the native Volcano /api segment with /ark
curl https://api.fornai.im/ark/v3/contents/generations/tasks \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-seedance-model-id",
    "content": [
      { "type": "text",
        "text": "A shiba inu running through the snow --ratio 16:9 --duration 5 --resolution 720p" },
      { "type": "image_url",
        "image_url": { "url": "https://.../dog.png" },
        "role": "first_frame" }
    ]
  }'

# Native Volcano response:{"id":"cgt-..."}

② Poll native Volcano response

curl https://api.fornai.im/ark/v3/contents/generations/tasks/cgt-xxx \
  -H "Authorization: Bearer sk-zerofa-xxx"

# 响应字段与官网查询接口同形:
# {"id":"cgt-...","model":"your-seedance-model-id","status":"succeeded",
#  "content":{"video_url":"https://...","last_frame_url":"https://..."},
#  "usage":{"completion_tokens":108900,"total_tokens":108900},
#  "created_at":1779354227,"updated_at":1779354426,
#  "seed":83017,"resolution":"720p","ratio":"16:9","duration":5,
#  "framespersecond":24,"service_tier":"default","execution_expires_after":172800,
#  "generate_audio":true,"draft":false,"priority":0,"output_format":"mp4"}

③ Task list (paginated)

curl "https://api.fornai.im/ark/v3/contents/generations/tasks?page_num=1&page_size=10&filter.status=succeeded" \
  -H "Authorization: Bearer sk-zerofa-xxx"

# {"total":30,"items":[
#   {"id":"cgt-...","model":"your-seedance-model-id","status":"succeeded",
#    "content":{"video_url":"https://...","last_frame_url":"https://..."},
#    "usage":{"completion_tokens":108900,"total_tokens":108900},
#    "created_at":1779354227,"updated_at":1779354426,
#    "seed":39832,"resolution":"720p","ratio":"16:9","duration":5,
#    "framespersecond":24,"service_tier":"default","execution_expires_after":172800,
#    "generate_audio":true,"draft":false,"priority":0,"output_format":"mp4"}]}

When to use it

The standard /v1/videos and /v1/images/generations endpoints cover common calls. Use /ark for newly released Volcano parameters, Seedance-specific controls, or native Seedream fields.

At present, /ark exposes image generation plus video task submission, query, and list endpoints. Use standard endpoints for other Volcano capabilities.

Path mapping: /ark replaces Volcano /api

Two URLs for the same endpoint

Volcano native  https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks
ZeroFA recommended   https://api.fornai.im/ark/v3/contents/generations/tasks

ZeroFA forwards the recommended path to Volcano /api/v3/contents/generations/tasks. The native Volcano request body, query parameters, and response format are preserved.

Connect through new-api

Open the complete new-api Volcano video setup guide →

new-api channel configuration

# Upstream settings in the new-api channel
API address / Base URL: https://api.fornai.im/ark
API Key: sk-zerofa-xxx
Model: your-seedance-model-id

Set the Base URL only through the /ark root; do not append a task path manually.

Two-step native Volcano flow

① Submit

POST /ark/v3/contents/generations/tasksNative Volcano bodyRequired

The body is the original Volcano Ark video task request with model and content. The original response is returned, including the Volcano task id. Submission is not charged.

② Poll

GET /ark/v3/contents/generations/tasks/:idid = Volcano task idRequired

The query is forwarded unchanged and returns the original Volcano response. status=succeeded includes content.video_url and triggers idempotent duration billing on the first success.

③ Task list (paginated)

GET /ark/v3/contents/generations/taskspage_num / page_size / filter.*Optional

page_numintegerOptional

Page number, starting at 1, default 1

page_sizeintegerOptional

Items per page, 1–100, default 10

filter.statusstringOptional

Filter by status, comma-separated: queued / running / succeeded / failed / cancelled

filter.task_idsstringOptional

Filter by task ids, comma-separated site task ids

filter.modelstringOptional

Filter by model name

filter.service_tierstringOptional

Accepted but currently does not affect filtering (this site routes at base model price)

This id is a native Volcano task id in cgt-* format. Query it through /ark/v3/.../:id. It is not interchangeable with the platform task id used by /v1/videos.

Draft mode

① Step 1: generate a 480p draft

# 样片模式 Step1：生成 480p 预览样片
# 顶层 draft:true + resolution 480p（仅支持 480p）
curl -X POST "https://api.fornai.im/ark/v3/contents/generations/tasks" \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-seedance-model-id",
    "content": [
      { "type": "text", "text": "一只柴犬在雪地奔跑 --ratio 16:9 --duration 5" }
    ],
    "draft": true,
    "resolution": "480p"
  }'

# → {"id":"cgt-..."}  记住这个 task id，Step2 需要用它

② Step 2: generate the 1080p final video from the draft id

# 样片模式 Step2：基于样片 ID 生成 1080p 成片
# content 只带 draft_task 引用，resolution 固定 1080p（仅支持 1080p）
curl -X POST "https://api.fornai.im/ark/v3/contents/generations/tasks" \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-seedance-model-id",
    "content": [
      { "type": "draft_task", "draft_task": { "id": "cgt-..." } }
    ],
    "resolution": "1080p"
  }'

# → 成片 resolution=1080p，其余参数（提示词/参考素材/时长/比例/seed/音频）由 Step1 自动复用

Draft mode parameters

draftbooleanOptional

Top-level draft:true enables draft mode. Only 480p is supported; any other resolution is rejected.

draft_task.idstringOptional

In Step 2, the content array carries a draft_task reference whose id is the task id from Step 1 (you may use this site's task id; the platform restores the Volcano task id automatically).

resolutionstringOptional

Step 1 is fixed at 480p and Step 2 at 1080p; any other resolution is rejected.

Use the official Volcano schema

Billing model

Successful video is settled by duration and model price; successful images are settled by actual image count. Failures release reservations, and unsettled results are not delivered.

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 native Volcano body

# Native Volcano body: content and advanced flags pass through unchanged
# Path rule: replace the native Volcano /api segment with /ark
curl https://api.fornai.im/ark/v3/contents/generations/tasks \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-seedance-model-id",
    "content": [
      { "type": "text",
        "text": "A shiba inu running through the snow --ratio 16:9 --duration 5 --resolution 720p" },
      { "type": "image_url",
        "image_url": { "url": "https://.../dog.png" },
        "role": "first_frame" }
    ]
  }'

# Native Volcano response:{"id":"cgt-..."}

② Poll native Volcano response

curl https://api.fornai.im/ark/v3/contents/generations/tasks/cgt-xxx \
  -H "Authorization: Bearer sk-zerofa-xxx"

# 响应字段与官网查询接口同形:
# {"id":"cgt-...","model":"your-seedance-model-id","status":"succeeded",
#  "content":{"video_url":"https://...","last_frame_url":"https://..."},
#  "usage":{"completion_tokens":108900,"total_tokens":108900},
#  "created_at":1779354227,"updated_at":1779354426,
#  "seed":83017,"resolution":"720p","ratio":"16:9","duration":5,
#  "framespersecond":24,"service_tier":"default","execution_expires_after":172800,
#  "generate_audio":true,"draft":false,"priority":0,"output_format":"mp4"}

③ Task list (paginated)

curl "https://api.fornai.im/ark/v3/contents/generations/tasks?page_num=1&page_size=10&filter.status=succeeded" \
  -H "Authorization: Bearer sk-zerofa-xxx"

# {"total":30,"items":[
#   {"id":"cgt-...","model":"your-seedance-model-id","status":"succeeded",
#    "content":{"video_url":"https://...","last_frame_url":"https://..."},
#    "usage":{"completion_tokens":108900,"total_tokens":108900},
#    "created_at":1779354227,"updated_at":1779354426,
#    "seed":39832,"resolution":"720p","ratio":"16:9","duration":5,
#    "framespersecond":24,"service_tier":"default","execution_expires_after":172800,
#    "generate_audio":true,"draft":false,"priority":0,"output_format":"mp4"}]}

Volcano Engine native passthrough (/ark)

When to use it

Path mapping: /ark replaces Volcano /api

Connect through new-api

Two-step native Volcano flow

Draft mode

Use the official Volcano schema

Billing model

Request and response bodies

Volcano Engine native passthrough (/ark)

When to use it

Path mapping: /ark replaces Volcano /api

Connect through new-api

Two-step native Volcano flow

Draft mode

Use the official Volcano schema

Billing model

Request and response bodies