Skip to main content
本页介绍如何在 kapon 中，通过 火山方舟 VolcArk 原生接口 调用 Doubao Seedance 视频模型，包括：
  • 文生视频（T2V）：doubao-seedance-1-0-pro、doubao-seedance-1-0-pro-fast、doubao-seedance-1-0-lite-t2v
  • 图生视频（I2V）：doubao-seedance-1-0-lite-i2v
所有请求都经由 kapon 转发到火山方舟，不需要自行签名，只需在 Header 中携带 kapon API Key。 
export BASE_URL="https://models.kapon.cloud"
export TOKEN="oh-xxxxxxxxxxxxxxxx"
统一使用： 
Authorization: Bearer <TOKEN>
Content-Type: application/json

​
接口总览

在 kapon 中，Doubao Seedance 的 VolcArk 原生接口统一挂载在：
  • 提交任务：POST /volcark/api/v3/contents/generations/tasks
  • 查询任务：GET /volcark/api/v3/contents/generations/tasks/{task_id}
  • 列表查询：GET /volcark/api/v3/contents/generations/tasks
  • 取消任务：DELETE /volcark/api/v3/contents/generations/tasks/{task_id}
你只需要关注上述 HTTP 路径和请求体结构，无需了解内部路由和代码实现细节。

​
请求体结构

创建 Seedance 视频任务时，请求体主体为： 
{
  "model": "doubao-seedance-1-0-pro",
  "content": [
    { "type": "text", "text": "一个男孩在草地上和小狗玩耍" }
  ]
}
重要字段说明：
  • model：Seedance 模型名称，平台会在内部通过 mapVolcArkSeedanceModel 统一映射为带版本 ID 的 Ark 模型（见 relay/task/volcark/submit.go），但对用户侧保持原始名字。
  • content：内容数组，支持多段内容。
    • 文生视频（T2V）：至少包含一条 type: "text" 的文本。
    • 图生视频（I2V）：必须同时包含文本和图片，其中图片使用 image_url 格式。
示例：图生视频（I2V）请求体： 
{
  "model": "doubao-seedance-1-0-lite-i2v",
  "content": [
    {
      "type": "text",
      "text": "一幅油画风格的海边日落场景"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seelite_first_frame.png"
      }
    }
  ]
}
对于图生视频模型（I2V，例如 doubao-seedance-1-0-lite-i2v），如果 content 中未包含图片（image_url），火山方舟会返回错误：
image to video models require image in content
请确保至少传入一张参考图。
常用附加参数（可选）：
  • duration / frames：控制视频时长；若同时指定，Ark 以 frames 为准；
  • ratio / aspect_ratio：画面宽高比，例如 16:9、9:16；
  • resolution：如 720p、1080p；
  • seed：随机种子，用于结果可复现；
  • 其他 Ark 官方文档支持的参数也会被透传，并在 relay/task/volcark/billing.go 中参与分辨率与计费估算。

​
文生视频示例（T2V）

以 Pro 模型 doubao-seedance-1-0-pro 为例： 
curl -X POST "$BASE_URL/volcark/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-1-0-pro",
    "content": [
      { "type": "text", "text": "一个男孩在草地上和小狗玩耍" }
    ],
    "duration": 6,
    "ratio": "16:9",
    "resolution": "720p"
  }'
成功时会返回任务 ID。原生 Ark 接口与平台全局视频任务 ID 并存： 
{
  "id": "cgt-xxxx",
  "platform_id": "video_<PlatformTaskID>"
}
其中：
  • id：火山方舟原生任务 ID（例如 cgt-2025...），可直接用于调用 Ark 官方文档中的查询/取消接口；
  • platform_id：平台全局视频任务 ID，前缀固定为 video_，与 /v1/videos 接口以及任务中心共用同一套 ID 体系。
平台会在后台记录任务，并通过 relay/task/volcark/billing.go 估算分辨率/时长与 token 用量，用于 /panel/log 与计费展示。

​
图生视频示例（I2V）

以 Lite 图生视频模型 doubao-seedance-1-0-lite-i2v 为例： 
curl -X POST "$BASE_URL/volcark/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-1-0-lite-i2v",
    "content": [
      {
        "type": "text",
        "text": "一幅油画风格的海边日落场景"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seelite_first_frame.png"
        }
      }
    ],
    "duration": 5,
    "ratio": "9:16",
    "resolution": "720p"
  }'
注意：
  • content 中图片 URL 支持公网可访问链接；
  • 推荐图片宽高比与目标视频一致（例如竖屏 9:16 对应竖版参考图）。

​
查询任务状态

创建任务后，可以使用 Ark 原生 ID 或 平台全局 ID 查询进度： 
export TASK_ID="cgt-xxxx"              # Ark 原生任务 ID
# 或使用平台全局视频任务 ID（推荐）：
# export TASK_ID="video_<PlatformTaskID>"

curl "$BASE_URL/volcark/api/v3/contents/generations/tasks/$TASK_ID" \
  -H "Authorization: Bearer $TOKEN"
典型成功响应（字段结构对齐 providers/volcark/video.go 中的 VolcArkVideoTask，平台会在上游响应基础上附加 platform_id 字段）： 
{
  "id": "cgt-xxxx",
  "platform_id": "video_<PlatformTaskID>",
  "model": "doubao-seedance-1-0-pro-250528",
  "status": "succeeded",
  "content": {
    "video_url": "https://xxx/xxx.mp4",
    "last_frame_url": "https://xxx/last_frame.png",
    "width": 1280,
    "height": 720
  },
  "duration": 6,
  "framespersecond": 16,
  "usage": {
    "video_tokens": 123456
  }
}
其中：
  • status：queued / running / succeeded / failed / cancelled；
  • content.video_url：成片地址，由 kapon 在 /panel/task 中直接展示；
  • usage.video_tokens：视频 token 用量，将用于计费。

​
取消任务与列表查询

取消任务： 
curl -X DELETE "$BASE_URL/volcark/api/v3/contents/generations/tasks/$TASK_ID" \
  -H "Authorization: Bearer $TOKEN"
分页查询任务： 
curl "$BASE_URL/volcark/api/v3/contents/generations/tasks?page_num=1&page_size=20" \
  -H "Authorization: Bearer $TOKEN"
支持的查询参数包括：
  • page_num / page_size：分页控制；
  • filter.status：任务状态；
  • filter.task_ids：指定任务 ID 列表；
  • filter.model：指定模型，如 doubao-seedance-1-0-pro。

​
计费与监控

Seedance 视频的价格已在 /panel/pricing 中按模型预设，计费会结合：
  • 请求中的时长（duration / frames）、分辨率等参数；
  • 上游返回的 usage 字段（若存在）。
你可以在：
  • 「调用日志」中查看每次请求的 token 用量与费用；
  • 「任务中心 / 视频任务」中查看任务状态、耗时和播放地址。

​
常见问题（FAQ）

​
1. I2V 提示 “image to video models require image in content”

原因是 model 为 I2V，但 content 中没有图片。请按本页示例增加： 
{
  "type": "image_url",
  "image_url": { "url": "https://..." }
}

​
2. 任务长时间处于 queued/running

  • 可以通过 GET /volcark/api/v3/contents/generations/tasks/{task_id} 查看 status 与 error 字段；
  • 若持续长时间未结束，可尝试 DELETE 取消任务并重新提交；
  • 后台会在任务进入终态时，通过 relay/task/volcark/log_video_terminal_status.go 记录耗时与异常信息，便于排查。

​
3. 如何区分 T2V / I2V 模型？

  • 文生视频：doubao-seedance-1-0-pro、doubao-seedance-1-0-pro-fast、doubao-seedance-1-0-lite-t2v
  • 图生视频：doubao-seedance-1-0-lite-i2v
在业务代码中，可以根据模型名动态决定是否强制要求 image_url。