视频生成 API 对接文档

统一视频生成接口，支持 Seedance（字节）、Kling（快手可灵）、Vidu、Grok、Omni 等多个视频模型。支持文生视频、图生视频。所有模型走同一套接口，只是请求体里 model 取值不同（见第二节「支持的模型」）。异步任务模式：提交任务拿到 task_id，再轮询查询结果。

服务地址：https://hub.nocannobb.com
协议：HTTPS + JSON
鉴权：API Key（Bearer Token）

一、准备工作

获取一个 API Key（sk- 开头），该 Key 需绑定「视频生成」服务分组。不同模型家族分属不同的服务分组，Key 需绑定你要调用的那个家族对应的分组，否则会鉴权/权限失败：
- Seedance / Kling / Vidu 同属一个视频分组；
- Grok 单独一个分组；
- Omni 单独一个分组。
确保账户余额充足（视频按时长计费，见第四节）。
所有请求都要带请求头：

Authorization: Bearer 你的APIKey

二、提交视频任务

POST /api/v1/video-tasks

请求头

请求头	必填	说明
`Authorization`	是	`Bearer 你的APIKey`
`Content-Type`	是	`application/json`
`Idempotency-Key`	是	幂等键。每个新任务用一个全局唯一字符串（如 UUID）。相同 Key + 相同请求体会返回同一个任务；相同 Key + 不同请求体会报冲突。

请求体参数

参数	类型	必填	说明
`model`	string	是	模型标识，如 `seedance-2.0`、`kling-2.6`、`vidu-q3`、`grok-video-10s`、`omni_flash-10s`。全部可选值见下方「支持的模型」
`prompt`	string	条件必填	视频提示词，建议写清主体、动作、场景、镜头、光线、风格。多数模型必填；标注「图生视频专用」的型号 `prompt` 可选
`duration`	number	否	视频时长（秒），范围 4–15，默认 5。按次计费的型号时长为固定档位（见说明）
`resolution`	string	否	各模型支持的分辨率不同（见下表）。默认 `720p`
`aspect_ratio`	string	否	画面比例：`16:9`、`9:16`、`3:4`、`4:3`、`1:1`、`21:9`、`adaptive`
`image`	string / 对象	否	首帧图片 URL；也可传对象 `{ "url": "..." }`
`image_tail`	string / 对象	否	尾帧图片 URL（仅 Seedance 支持）；也可传对象 `{ "url": "..." }`
`images`	数组	否	多图参考，URL 数组（或对象数组）。Seedance 最多 9 个；Grok（`grok-imagine-video` / `grok-video-10s` / `grok-video-15s`）最多 7 个，为参考图语义（见「各家族输入差异」），prompt 中可用 `@image1`、`@image2` 指代各图。其余型号不支持
`video`	string / 数组	否	参考视频 URL（仅 Seedance 支持），最多 3 个

所有素材 URL（image / image_tail / images / video）必须是公网可访问的 HTTPS 地址。

支持的模型

model 取下表中的值。各家族能力不同，注意分辨率、时长、输入与计费方式的差异。

`model`	家族	计费	分辨率	时长	输入与限制
`seedance-2.0`	Seedance	按秒	480p/720p/1080p/4k	4–15s	文生/图生，支持首帧图、多图参考、参考视频
`seedance-2.0-fast`	Seedance	按秒	480p/720p	4–15s	同上，出片更快
`seedance-2.0-mini`	Seedance	按秒	480p/720p	4–15s	同上，更低成本
`kling-1.0` `kling-1.5` `kling-1.6` `kling-2.0` `kling-2.1` `kling-2.1m`	Kling	按秒	720p/1080p	4–15s	文生/图生（首帧图）
`kling-2.5` `kling-2.6`	Kling	按秒	720p/1080p	4–15s	文生/图生（首帧图），更高性价比
`kling-o1`	Kling	按秒	720p/1080p	4–15s	文生/图生（首帧图），旗舰画质
`vidu-q2` `vidu-q2-turbo`	Vidu	按秒	720p/1080p	4–15s	文生/图生（首帧图）
`vidu-q2-pro` `vidu-q2-pro-fast`	Vidu	按秒	720p/1080p	4–15s	文生/图生（首帧图）
`vidu-q3` `vidu-q3-turbo`	Vidu	按秒	540p/720p/1080p	4–15s	文生/图生（首帧图）
`vidu-q3-mix`	Vidu	按秒	720p/1080p	4–15s	文生/图生（首帧图）
`vidu-q3-pro`	Vidu	按秒	540p/720p/1080p	4–15s	文生/图生（首帧图），旗舰画质
`grok-imagine-video`	Grok	按秒	720p	4–15s	文生/图生（首帧），支持多图参考 `images`（≤7）
`grok-imagine-video-1.5-preview`	Grok	按秒	720p	4–15s	仅图生视频，必须传 `image`，`prompt` 可选
`grok-video-10s`	Grok	按次	720p	固定 10s	文生/图生（首帧），支持多图参考 `images`（≤7）
`grok-video-15s`	Grok	按次	720p	固定 15s	文生/图生（首帧），支持多图参考 `images`（≤7）
`grok-video-1.5-preview-10s`	Grok	按次	720p	固定 10s	仅图生视频，必须传 `image`
`grok-video-1.5-preview-15s`	Grok	按次	720p	固定 15s	仅图生视频，必须传 `image`
`omni_flash-10s`	Omni	按秒	720p	固定 10s	文生/图生（首帧）

各家族输入差异：
Seedance 输入最丰富：首帧图 image、尾帧图 image_tail、多图参考 images（≤9）、参考视频 video（≤3）；
Grok（grok-imagine-video / grok-video-10s / grok-video-15s）支持首帧图 image 和多图参考 images（≤7）。注意 Grok 的多图是参考图语义：参考图影响画面中出现的内容，但不锁定首帧（与 Seedance 的首帧语义不同）；prompt 中可用 @image1、@image2 指代各图。不支持 image_tail / video；
Kling / Vidu / Omni 及 Grok *-1.5-preview 系列仅支持首帧图 image，不支持 image_tail / images / video；
标「按次」的模型时长是固定档位（10s / 15s），duration 以固定值为准，填别的值无效；
*-1.5-preview 系列为图生视频专用，必须提供 image，prompt 可选。

响应（HTTP 202）

json

{
  "object": "video_task",
  "task_id": "videotask_3a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d",
  "status": "queued",
  "model": "seedance-2.0-fast",
  "resolution": "720p",
  "duration": 5,
  "billing": { "status": "not_billed", "estimated_cost": 5.2 },
  "created_at": "2026-06-28T22:00:00+08:00",
  "updated_at": "2026-06-28T22:00:00+08:00"
}

拿到 task_id 后，进入第三节轮询查询。billing.estimated_cost 是预估费用（元）。

三、查询任务结果

GET /api/v1/video-tasks/{task_id}

请求头：Authorization: Bearer 你的APIKey

响应（HTTP 200）

生成中：

json

{ "object": "video_task", "task_id": "videotask_xxx", "status": "running",
  "billing": { "status": "not_billed", "estimated_cost": 5.2 } }

成功：

json

{
  "object": "video_task",
  "task_id": "videotask_xxx",
  "status": "succeeded",
  "billing": { "status": "settled", "customer_cost": 5.2 },
  "result": {
    "object": "video",
    "video_url": "https://hub.nocannobb.com/api/v1/video-content/videotask_xxx?exp=...&sig=..."
  },
  "completed_at": "2026-06-28T22:03:00+08:00"
}

失败：

json

{
  "object": "video_task",
  "task_id": "videotask_xxx",
  "status": "failed",
  "billing": { "status": "not_billed" },
  "error": { "code": "upstream_task_failed", "message": "失败原因..." }
}

任务状态 `status`

状态	含义
`queued`	已排队，等待处理
`running`	生成中
`succeeded`	成功 —— 视频地址在 `result.video_url`
`failed`	失败 —— 原因在 `error.message`，不扣费

视频生成通常耗时 30 秒 ~ 3 分钟。请异步轮询，建议间隔 3–5 秒。 result.video_url 是平台签名地址，有有效期，请及时下载保存。

四、计费说明

计费分两种方式：按秒（单价 × 时长）和按次（固定一口价，与时长无关）。模型属于哪种见第二节「支持的模型」。失败任务不扣费。

按秒计费

计费公式：分辨率单价(元/秒) × 时长(秒)。

Seedance（单价表，元/秒；「含参考视频」= 请求带 video 参考视频时的单价）：

模型	480p	720p	1080p	4k
seedance-2.0	0.65（含参考 0.39）	1.30（0.78）	3.25（1.82）	7.80（4.81）
seedance-2.0-fast	0.52（0.26）	1.04（0.52）	—	—
seedance-2.0-mini	0.26（0.13）	0.65（0.39）	—	—

Kling（元/秒）：

模型	720p	1080p
kling-1.0 / 1.5 / 1.6 / 2.0 / 2.1 / 2.1m	0.624	1.092
kling-2.5 / 2.6	0.468	0.78
kling-o1	1.404	1.872

Vidu（元/秒）：

模型	540p	720p	1080p
vidu-q2	—	0.416	0.611
vidu-q2-turbo	—	0.325	0.611
vidu-q2-pro / q2-pro-fast	—	0.455	0.91
vidu-q3 / q3-turbo	0.65	0.91	1.04
vidu-q3-mix	—	1.30	1.56
vidu-q3-pro	0.91	1.95	2.08

Grok / Omni（按秒部分，元/秒）：

模型	720p
grok-imagine-video	0.047
grok-imagine-video-1.5-preview	0.070
omni_flash-10s	0.143（时长固定 10s，约 1.43 元/次）

示例：seedance-2.0-fast 720p、5 秒 → 1.04 × 5 = 5.2 元。
示例：seedance-2.0 720p、5 秒、带参考视频 → 0.78 × 5 = 3.9 元。

按次计费

每次任务一口价，与时长无关（时长为固定档位）：

模型	分辨率	单价（元/次）
grok-video-10s	720p	0.468
grok-video-15s	720p	0.702
grok-video-1.5-preview-10s	720p	0.702
grok-video-1.5-preview-15s	720p	1.053

通用规则

失败任务不扣费（两种计费方式都适用）。
提交时返回 billing.estimated_cost（预估），成功后 billing.customer_cost（实际扣费）。
Seedance 传参考视频 video 时，按上表「含参考视频」单价计费。

五、完整调用示例

文生视频（curl）

bash

# 1. 提交任务
curl -X POST https://hub.nocannobb.com/api/v1/video-tasks \
  -H "Authorization: Bearer 你的APIKey" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "seedance-2.0-fast",
    "prompt": "一只柯基在日落沙滩奔跑，电影感运镜，暖色调",
    "duration": 5,
    "resolution": "720p"
  }'
# 响应里取 task_id

# 2. 轮询查询（每 3-5 秒一次，直到 status 为 succeeded / failed）
curl https://hub.nocannobb.com/api/v1/video-tasks/videotask_xxx \
  -H "Authorization: Bearer 你的APIKey"
# status=succeeded 后，从 result.video_url 取视频地址

图生视频

在请求体里加 image（首帧图 URL）。所有家族都支持首帧图：

bash

curl -X POST https://hub.nocannobb.com/api/v1/video-tasks \
  -H "Authorization: Bearer 你的APIKey" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "kling-2.6",
    "prompt": "镜头缓缓推进，人物自然转头微笑",
    "image": "https://example.com/first-frame.jpg",
    "duration": 6,
    "resolution": "720p",
    "aspect_ratio": "9:16"
  }'

Seedance 高级用法：在请求体里加 image_tail 实现首尾帧过渡；加 images: ["url1","url2",...]（最多 9 个）用多图作为参考；加 video: "..." 用视频作为参考。image_tail / video 仅 Seedance 支持。
Grok 多图参考：grok-imagine-video / grok-video-10s / grok-video-15s 也支持 images（最多 7 个），为参考图语义——参考图决定画面里出现什么，但不锁定首帧；prompt 里可用 @image1、@image2 指代，例如 "prompt": "@image1 的苹果滚向 @image2 的餐盘"。Kling / Vidu / Omni 仅支持首帧图 image。

Python 示例

python

import time, uuid, requests

BASE = "https://hub.nocannobb.com"
API_KEY = "你的APIKey"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# 1. 提交
resp = requests.post(
    f"{BASE}/api/v1/video-tasks",
    headers={**HEADERS, "Content-Type": "application/json",
             "Idempotency-Key": str(uuid.uuid4())},
    json={
        "model": "seedance-2.0-fast",
        "prompt": "一只柯基在日落沙滩奔跑，电影感运镜",
        "duration": 5,
        "resolution": "720p",
    },
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["task_id"]
print("task_id:", task_id)

# 2. 轮询
while True:
    time.sleep(4)
    r = requests.get(f"{BASE}/api/v1/video-tasks/{task_id}",
                     headers=HEADERS, timeout=30)
    data = r.json()
    status = data["status"]
    print("status:", status)
    if status == "succeeded":
        url = data["result"]["video_url"]
        print("视频地址:", url)
        break
    if status == "failed":
        print("生成失败:", data.get("error", {}).get("message"))
        break

六、错误处理

HTTP	说明
401	鉴权失败 —— API Key 缺失或无效
400	请求参数错误（如缺少 `model` / `prompt` / `Idempotency-Key`，或不支持的模型/分辨率组合）
404	任务不存在（`task_id` 错误）
余额不足	提交被拒绝，请先充值

任务本身失败（上游生成失败）不会返回 HTTP 错误，而是查询时 status 为 failed、error.message 给出原因，且不扣费。

七、注意事项

视频生成是异步的，必须轮询查询，不要同步等待。
轮询间隔建议 3–5 秒；单个任务通常 30 秒 ~ 3 分钟完成。
图生视频的图片 URL 必须是公网可访问的 HTTPS 地址。
Idempotency-Key 每个新任务都要用不同的唯一值；网络超时重试时复用同一个 Key 可避免重复创建任务。
seedance-2.0-fast / seedance-2.0-mini 出片快、成本低，适合预览与批量；seedance-2.0 画质更高、支持 1080p/4k。
Kling / Vidu / Omni 及 Grok *-1.5-preview 系列仅支持首帧图 image；Grok 其余型号（grok-imagine-video / grok-video-10s / grok-video-15s）额外支持多图参考 images（≤7，参考图语义不锁首帧）；首尾帧、参考视频仍仅 Seedance 支持。
按次计费的模型（grok-video-*）时长为固定档位，预估与实际费用是固定一口价，与所填 duration 无关。
不同模型家族分属不同服务分组，调用前确认 API Key 已绑定对应分组。

视频生成 API 对接文档 ​

一、准备工作 ​

二、提交视频任务 ​

请求头 ​

请求体参数 ​

支持的模型 ​

响应（HTTP 202） ​

三、查询任务结果 ​

响应（HTTP 200） ​

任务状态 status ​

四、计费说明 ​

按秒计费 ​

按次计费 ​

通用规则 ​

五、完整调用示例 ​

文生视频（curl） ​

图生视频 ​

Python 示例 ​

六、错误处理 ​

七、注意事项 ​

视频生成 API 对接文档

一、准备工作

二、提交视频任务

请求头

请求体参数

支持的模型

响应（HTTP 202）

三、查询任务结果

响应（HTTP 200）

任务状态 `status`

四、计费说明

按秒计费

按次计费

通用规则

五、完整调用示例

文生视频（curl）

图生视频

Python 示例

六、错误处理

七、注意事项