概述

API Router 提供统一的 RESTful API 接口，用于调用多家上游 AI 模型供应商的能力。当前已支持 火山方舟（Volcano Ark） 的全系列视频生成模型。

所有 API 调用均通过标准 HTTP 请求完成，请求和响应体均为 JSON 格式。

鉴权认证

所有 API 请求须通过 Authorization Header 携带 API Key 进行鉴权：

Authorization: Bearer YOUR_API_KEY

您可以在 控制台 > API Keys 页面创建和管理 API Key。每个账户最多创建 10 个 Key。

Base URL

所有 API 请求的基础地址：

https://api.fclink.cn/api/v1

错误码

HTTP 状态码说明
200请求成功
400请求参数错误
401认证失败（API Key 无效或缺失）
402余额不足
403权限不足
404资源不存在
429请求频率超限
502上游服务错误

创建视频生成任务

POST /api/v1/video/generations

创建一个异步视频生成任务。支持文生视频、图生视频（首帧/首尾帧/参考图）、有声视频等多种模式。

请求参数（Request Body）

参数类型必填说明
model string 是 模型 ID，如 doubao-seedance-1-5-pro-251215
content array 是 输入内容数组，包含文本和/或图片对象
resolution string 否 视频分辨率：480p、720p（默认）、1080p
ratio string 否 宽高比：16:9（默认）、4:3、1:1、3:4、9:16、21:9、adaptive
duration integer 否 视频时长（秒），2~12。Seedance 1.5 Pro 支持 4~12，设为 -1 可让模型自动选择
seed integer 否 随机种子，默认 -1（随机）
camera_fixed boolean 否 是否固定摄像头，默认 false
watermark boolean 否 是否添加水印，默认 false
generate_audio boolean 否 是否生成同步音频（仅 Seedance 1.5 Pro），默认 true
draft boolean 否 是否开启样片模式（仅 Seedance 1.5 Pro），默认 false
return_last_frame boolean 否 是否返回尾帧图像，默认 false
service_tier string 否 服务等级：default（在线推理）或 flex（离线推理，价格50%）
execution_expires_after integer 否 任务超时阈值（秒），范围 3600~259200，默认 172800（48小时）

Content 数组对象说明

文本对象：

{
  "type": "text",
  "text": "描述期望生成的视频内容"
}

图片对象：

{
  "type": "image_url",
  "image_url": {
    "url": "图片URL 或 data:image/png;base64,{base64编码}"
  },
  "role": "first_frame"  // 可选：first_frame / last_frame / reference_image
}

图片要求：格式 jpeg/png/webp/bmp/tiff/gif；宽高比 (0.4, 2.5)；宽高像素 (300, 6000)px；大小 < 30MB。

响应

{
  "id": "cgt-2025xxxxxx-xxxx"
}

返回任务 ID，需通过查询接口获取任务状态和结果。

查询视频生成任务

GET /api/v1/video/generations/{task_id}

查询视频生成任务的当前状态和结果。任务成功后返回视频 URL。

路径参数

参数类型说明
task_id string 视频生成任务 ID

响应参数

字段类型说明
idstring任务 ID
modelstring模型名称及版本
statusstring任务状态：queued / running / succeeded / failed / cancelled / expired
content.video_urlstring生成视频 URL (mp4)，有效期 24 小时
content.last_frame_urlstring尾帧图像 URL（如设置 return_last_frame）
usage.total_tokensinteger总 Token 消耗
seedinteger使用的种子值
resolutionstring视频分辨率
ratiostring视频宽高比
durationinteger视频时长（秒）
errorobject/null错误信息（失败时）

响应示例

{
  "id": "cgt-2025xxxxxx-xxxx",
  "model": "doubao-seedance-1-5-pro-251215",
  "status": "succeeded",
  "content": {
    "video_url": "https://ark-content-generation-cn-beijing.tos-cn-beijing.volces.com/xxx"
  },
  "usage": {
    "completion_tokens": 108900,
    "total_tokens": 108900
  },
  "created_at": 1743414619,
  "updated_at": 1743414673,
  "seed": 10,
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "framespersecond": 24,
  "service_tier": "default",
  "generate_audio": true,
  "draft": false
}

取消视频生成任务

POST /api/v1/video/generations/{task_id}/cancel

取消排队中的视频生成任务。仅 queued 状态的任务可以被取消。

示例：文生视频

使用文本描述生成视频：

curl -X POST http://localhost:8000/api/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "doubao-seedance-1-0-pro-250528",
    "content": [
      {
        "type": "text",
        "text": "写实风格，晴朗的蓝天之下，一大片白色的雏菊花田，镜头逐渐拉近，最终定格在一朵雏菊花的特写上"
      }
    ],
    "ratio": "16:9",
    "duration": 5,
    "watermark": false
  }'

查询任务结果：

curl http://localhost:8000/api/v1/video/generations/cgt-2025xxxxxx-xxxx \
  -H "Authorization: Bearer YOUR_API_KEY"

示例：图生视频（首帧）

上传首帧图片，生成视频：

curl -X POST http://localhost:8000/api/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "doubao-seedance-1-0-pro-250528",
    "content": [
      {
        "type": "text",
        "text": "镜头缓慢拉远，展现整个城市全景"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/city.jpg"
        },
        "role": "first_frame"
      }
    ],
    "ratio": "16:9",
    "duration": 5
  }'

示例：有声视频（Seedance 1.5 Pro）

curl -X POST http://localhost:8000/api/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "doubao-seedance-1-5-pro-251215",
    "content": [
      {
        "type": "text",
        "text": "男人叫住女人说：\"你记住，以后不可以用手指指月亮。\""
      }
    ],
    "generate_audio": true,
    "ratio": "16:9",
    "duration": 5
  }'

支持的模型

模型Model ID能力
Seedance 1.5 Pro doubao-seedance-1-5-pro-251215 文/图生视频、首尾帧、有声视频、样片模式
Seedance 1.0 Pro doubao-seedance-1-0-pro-250528 文/图生视频、首尾帧
Seedance 1.0 Pro Fast doubao-seedance-1-0-pro-fast-250528 文/图生视频（快速模式）
Seedance 1.0 Lite (T2V) doubao-seedance-1-0-lite-t2v 文生视频
Seedance 1.0 Lite (I2V) doubao-seedance-1-0-lite-i2v 图生视频、首尾帧、参考图

计费说明

API Router 按 Token 用量 计费。只计算输出 Token（completion_tokens），不计算输入 Token。

请联系管理员充值余额或了解更多定价信息。

集成最佳实践

  1. 异步轮询：创建任务后返回任务 ID，建议每 5~10 秒轮询一次查询接口，直至任务完成。
  2. 及时转存：生成的视频 URL 有效期 24 小时，请及时下载转存。
  3. 错误处理：捕获 HTTP 错误码，做好重试与降级逻辑。
  4. 余额监控：通过仪表盘或 API 定期检查余额，避免服务中断。