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. 前置条件

HTTP 头部：
控制台需要将以下模型名映射到 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 为例：
典型成功返回：
说明：
  • 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）：
对于 I2V 模型（如 doubao-seedance-1-0-lite-i2v），若未提供任何图片引用，平台会返回错误：
image to video models require image in content

​
5. 查询任务状态

创建任务后，可通过 id 查询最新状态：
典型返回：
说明：
  • 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：

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

推荐使用：
  • 如希望与 OpenAI Sora/Veo 风格统一，优先使用本页的 /v1/videos 接口；
  • 如需完全对齐火山方舟官方文档（原生字段），可使用 doubao/video 文档中的 VolcArk 原生接口。