Skip to content

视频(原生) ​

通过 /volcark/api/v3/contents/generations/tasks 使用 Doubao Seedance 视频模型(含文生视频与图生视频)。

本页介绍如何在 Fhddos 中,通过 火山方舟 VolcArk 原生接口 调用 Doubao Seedance 视频模型,包括:

  • 文生视频(T2V):doubao-seedance-1-5-pro、doubao-seedance-1-0-pro、doubao-seedance-1-0-pro-fast、doubao-seedance-1-0-lite-t2v
  • 图生视频(I2V):doubao-seedance-1-0-lite-i2v

本页覆盖的是 Doubao Seedance 1.x 原生接口。
如果你要接入 Seedance 2.5,请改看 Seedance 2.5;国内 Doubao Seedance 2.0 和海外 BytePlus Dreamina Seedance 2.0 分别见 Doubao Seedance 2.0 与 BytePlus Dreamina Seedance 2.0。

所有请求都经由 Fhddos 转发到火山方舟,不需要自行签名,只需在 Header 中携带 Fhddos API Key。

bash
export BASE_URL="https://aiapi.fhddos.com"
export TOKEN="oh-xxxxxxxxxxxxxxxx"

统一使用:

http
Authorization: Bearer <TOKEN>
Content-Type: application/json

接口总览 ​

在 Fhddos 中,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 视频任务时,请求体主体为:

json
{
  "model": "doubao-seedance-1-0-pro",
  "content": [
    { "type": "text", "text": "一个男孩在草地上和小狗玩耍" }
  ]
}

重要字段说明:

  • model:Seedance 模型名称,平台会在内部自动映射为版本化的模型 ID(如 doubao-seedance-1-5-pro-251215),但对用户侧保持使用原始 API 模型名。
  • content:内容数组,支持多段内容。
    • 文生视频(T2V):至少包含一条 type: "text" 的文本。
    • 图生视频(I2V):必须同时包含文本和图片,其中图片使用 image_url 格式。

示例:图生视频(I2V)请求体:

json
{
  "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"
      }
    }
  ]
}

WARNING

对于图生视频模型(I2V,例如 doubao-seedance-1-0-lite-i2v),如果 content 中未包含图片(image_url),火山方舟会返回错误:


image to video models require image in content


请确保至少传入一张参考图。

常用附加参数(可选):

  • duration / frames:控制视频时长;若同时指定,以 frames 为准;
  • ratio / aspect_ratio:画面宽高比,例如 16:9、9:16;
  • resolution:如 720p、1080p;
  • seed:随机种子,用于结果可复现;
  • 其他官方文档支持的参数也会被透传,平台会根据分辨率与时长自动计算计费用量。

文生视频示例(T2V) ​

以 Pro 模型 doubao-seedance-1-0-pro 为例:

bash
curl -X POST "https://aiapi.fhddos.com/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 并存:

json
{
  "id": "cgt-xxxx",
  "platform_id": "video_<PlatformTaskID>"
}

其中:

  • id:火山方舟原生任务 ID(例如 cgt-2025...),可直接用于调用 Ark 官方文档中的查询/取消接口;
  • platform_id:平台全局视频任务 ID,前缀固定为 video_,与 /v1/videos 接口以及任务中心共用同一套 ID 体系。

平台会在后台记录任务,并根据分辨率/时长自动估算 token 用量,用于计费展示。

图生视频示例(I2V) ​

以 Lite 图生视频模型 doubao-seedance-1-0-lite-i2v 为例:

bash
curl -X POST "https://aiapi.fhddos.com/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 查询进度:

bash
export TASK_ID="cgt-xxxx"              # Ark 原生任务 ID
# 或使用平台全局视频任务 ID(推荐):
# export TASK_ID="video_<PlatformTaskID>"

curl "https://aiapi.fhddos.com/volcark/api/v3/contents/generations/tasks/$TASK_ID" \
  -H "Authorization: Bearer $TOKEN"

典型成功响应(平台会在标准响应基础上附加 platform_id 字段):

json
{
  "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:成片地址,由 Fhddos 在 /panel/task 中直接展示;
  • usage.video_tokens:视频 token 用量,将用于计费。

取消任务与列表查询 ​

取消任务:

bash
curl -X DELETE "https://aiapi.fhddos.com/volcark/api/v3/contents/generations/tasks/$TASK_ID" \
  -H "Authorization: Bearer $TOKEN"

分页查询任务:

bash
curl "https://aiapi.fhddos.com/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 中没有图片。请按本页示例增加:

json
{
  "type": "image_url",
  "image_url": { "url": "https://..." }
}

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

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

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。

Fhddos AI 用户文档