Skip to main content
本页介绍如何在 kapon 中，使用 OpenAI 风格的视频接口 /v1/videos 调用火山方舟 Doubao Seedance 视频模型，并与官方 Sora/Veo 接口保持一致的体验：
  • 统一的请求体：model / prompt / seconds / size / input_reference；
  • 统一的任务 ID：响应中的 id 均为 video_<PlatformTaskID> 形式；
  • 统一的查询方式：GET /v1/videos/{id}。
对比关系：
  • 原生 Ark 接口：POST /volcark/api/v3/contents/generations/tasks（见 doubao/video 文档）
  • OpenAI 风格接口（本页）：POST /v1/videos

​
1. 前置条件

export BASE_URL="https://models.kapon.cloud/v1"
export TOKEN="oh-xxxxxxxxxxxxxxxx"
HTTP 头部： 
Authorization: Bearer <TOKEN>
Content-Type: application/json
控制台需要将以下模型名映射到 VolcArk Doubao Seedance 渠道：
  • doubao-seedance-1-0-pro
  • doubao-seedance-1-0-pro-fast
  • doubao-seedance-1-0-lite-t2v
  • doubao-seedance-1-0-lite-i2v

​
2. OpenAI 风格接口概览

在 OpenAI 风格模式下，你只需要关注统一的 /v1/videos 接口：
  • 创建任务：POST /v1/videos
  • 查询任务：GET /v1/videos/{id}
  • 下载内容：GET /v1/videos/{id}/content

​
3. 文生视频示例（T2V）

以 doubao-seedance-1-0-pro-fast 为例： 
curl -X POST "$BASE_URL/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-1-0-pro-fast",
    "prompt": "夜晚城市街道上的车辆灯光流动",
    "seconds": 8,
    "size": "1280x720"
  }'
典型成功返回： 
{
  "id": "video_01KB1Y6FT0QMDKS0Y1YYYSS4D0",
  "object": "video",
  "status": "queued",
  "model": "doubao-seedance-1-0-pro-fast",
  "seconds": 8,
  "size": "1280x720"
}
说明：
  • id：平台生成的全局任务 ID，始终以 video_ 开头；
    • 其内部对应 model.Task.PlatformTaskID；
    • 在 /panel/task 页面中你会看到同一个值（列名为「任务ID」）。
  • model：保留对外暴露的 API 模型名（例如 doubao-seedance-1-0-pro-fast），不会泄露 Ark 内部版本化 ID。

​
4. 图生视频示例（I2V）

图生视频模型通过 input_reference 传入参考图 URL（兼容 input_image / input_images）： 
curl -X POST "$BASE_URL/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-1-0-lite-i2v",
    "prompt": "一幅油画风格的海边日落场景",
    "seconds": 6,
    "size": "720x1280",
    "input_reference": [
      "https://ark-project.tos-cn-beijing.volces.com/doc_image/seelite_first_frame.png"
    ]
  }'
对于 I2V 模型（如 doubao-seedance-1-0-lite-i2v），若未提供任何图片引用，平台会返回错误：
image to video models require image in content

​
5. 查询任务状态

创建任务后，可通过 id 查询最新状态： 
export VIDEO_ID="video_01KB1Y6FT0QMDKS0Y1YYYSS4D0"

curl "$BASE_URL/videos/$VIDEO_ID" \
  -H "Authorization: Bearer $TOKEN"
典型返回： 
{
  "id": "video_01KB1Y6FT0QMDKS0Y1YYYSS4D0",
  "object": "video",
  "status": "completed",
  "model": "doubao-seedance-1-0-pro-fast",
  "seconds": 8,
  "size": "1280x720",
  "video_url": "https://proxy.kapon.cloud/video/01KB1Y6FT0QMDKS0Y1YYYSS4D0.mp4"
}
说明：
  • status：queued / in_progress / completed / failed 等；
  • video_url：
    • 为平台代理后的 URL（由 proxyVideoURLs 生成），不会暴露 Ark 源站域名；
    • 同一 URL 会出现在 /panel/task 弹窗中的「平台最终响应」里。
内部映射过程：
  • relay.VideoRetrieve 会根据 video_ 前缀将 VIDEO_ID 还原为内部 PlatformTaskID；
  • 根据任务的 Platform（sora 或 volcark）选择对应 Provider；
  • 对 VolcArk 任务，调用 providers/volcark/video.go 的 RetrieveVideo，使用 Ark 的 task_id 查询最新状态。

​
6. 下载视频内容

下载内容与 Sora/Veo 对齐，使用 /v1/videos/{id}/content： 
curl -L "$BASE_URL/videos/$VIDEO_ID/content" \
  -H "Authorization: Bearer $TOKEN" \
  -o doubao-seedance-demo.mp4

​
7. 与原生 VolcArk 接口的对比

维度原生 VolcArk 接口OpenAI 风格接口 /v1/videos
创建路径/volcark/api/v3/contents/generations/tasks/v1/videos
请求体model + content[{type,text/image_url,...}]model + prompt + seconds + size + input_reference
任务 IDArk 的 id / task_id（不带前缀）平台全局 ID：video_<PlatformTaskID>
查询路径/volcark/api/v3/contents/generations/tasks/{task_id}/v1/videos/{id}
控制台任务列表PlatformTaskID（原生：裸 ULID；现在：带 video_ 前缀）同一值，展示为 video_<PlatformTaskID>
推荐使用：
  • 如希望与 OpenAI Sora/Veo 风格统一，优先使用本页的 /v1/videos 接口；
  • 如需完全对齐火山方舟官方文档（原生字段），可使用 doubao/video 文档中的 VolcArk 原生接口。