视频生成

POST /v1/videos —— 异步任务：创建、轮询、取产物。

创建任务#

视频模型只走这条端点。把视频模型名发到 /v1/chat/completions 会被直接拒绝并提示改用本端点——那样比让请求跑到上游再拿一个含糊的错误好。

modelstring必填: 视频模型名，可在模型广场按视频模态筛选。
promptstring: 文本提示词。prompt 与参考图至少要给一个，两个都没有返回 invalid_request。
input_referencestring | file: 参考图/首帧。JSON 里给可访问的 URL 或 data URL；也可以把整个请求改成 multipart/form-data 直接上传文件。带参考视频的模型按 per_token 的「含参考视频」那一档计价。
secondsstring | integer必填: 时长秒数，字符串与整数都接受。
sizestring: 如 1280x720。入站会拆成 resolution 与 aspect_ratio。
resolutionstring: 480p / 720p / 1080p / 4k。
aspect_ratiostring: 如 16:9、9:16。
fpsinteger: 帧率。
generate_audioboolean: 是否同时生成音轨（取决于模型是否支持）。
watermarkboolean: 是否加水印。
seedinteger: 随机种子，用于复现同一结果。
callback_urlstring: 任务终态回调地址。给了它就不必轮询。

重复提交是安全的

带上 Idempotency-Key 请求头，重复提交会返回首次创建的那个任务，而不是再生成一条。

bash

curl https://ai.oceango.hk/v1/videos \  -H "Authorization: Bearer $AIROUTER_API_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: my-job-001" \  -d '{    "model": "doubao-seedance-1-0-pro",    "prompt": "A cat surfing a wave, cinematic",    "seconds": 5,    "resolution": "720p",    "aspect_ratio": "16:9"  }'

轮询状态#

创建接口返回的 id 就是任务号，用 GET /v1/videos/{id} 轮询到终态即可。

status	含义
`queued`	已排队，还没开始。此时可以取消。
`in_progress`	正在生成。
`completed`	完成，`content.video_url` 给出产物地址。
`failed`	失败，`error.code` 与 `error.message` 给出原因。

bash

curl https://ai.oceango.hk/v1/videos/$VIDEO_ID \  -H "Authorization: Bearer $AIROUTER_API_KEY"

响应里的 progress 是百分比进度（上游给出时才有）。建议轮询间隔从 2 秒起，别用 200 毫秒去打——它不会让视频更快生成，只会更早撞上限流。

Python：完整跑一遍，退避着轮询到终态

python

import os, time, requests
API = "https://ai.oceango.hk/v1"HEADERS = {"Authorization": f"Bearer {os.environ['AIROUTER_API_KEY']}"}
# 1. 创建任务，立刻拿到任务号（不是视频）task = requests.post(    API + "/videos",    headers=HEADERS,    json={"model": "volcengine/doubao-seedance", "prompt": "一只柴犬在维港边慢跑，电影感镜头"},    timeout=60,).json()
# 2. 轮询。间隔从 2 秒起逐步拉长，封顶 15 秒——#    打得再密视频也不会更快生成，只会更早撞上限流。delay = 2while True:    time.sleep(delay)    delay = min(delay * 1.5, 15)
    state = requests.get(API + "/videos/" + task["id"], headers=HEADERS, timeout=30).json()    if state["status"] == "completed":        print(state["content"]["video_url"])        break    if state["status"] == "failed":        raise RuntimeError(state["error"]["message"])    print(state["status"], state.get("progress", ""))

列表、下载与取消#

端点	说明
`GET /v1/videos`	列出当前 Key 所属用户的任务，支持 `limit`（1–100，默认 20）与 `offset`。
`GET /v1/videos/{id}/content`	302 重定向到产物地址，方便直接下载。
`DELETE /v1/videos/{id}`	取消任务。`queued` 可取消；已经在跑的返回 409。

计费#

视频有两种对客计费模式：按秒（per_second）与按 token（per_token，含/不含参考视频两档）。具体用哪种取决于模型接的上游，模型广场的卡片与详情页显示的就是这两种口径。

按秒计费的模型，单价可能随分辨率分档，开音轨也可能另算——详情页显示的是实际生效的那一档。
创建任务时就会冻结一笔预扣。视频的预扣按估算的最终金额来，不像对话那样再乘 1.2；租约 60 分钟，任务还在跑就自动续期。
失败与取消的任务不收费，口径与对话端点一致，见计费口径。

创建任务#

视频模型只走这条端点。把视频模型名发到 /v1/chat/completions 会被直接拒绝并提示改用本端点——那样比让请求跑到上游再拿一个含糊的错误好。

modelstring必填

视频模型名，可在模型广场按视频模态筛选。

promptstring

文本提示词。prompt 与参考图至少要给一个，两个都没有返回 invalid_request。

input_referencestring | file

参考图/首帧。JSON 里给可访问的 URL 或 data URL；也可以把整个请求改成 multipart/form-data 直接上传文件。带参考视频的模型按 per_token 的「含参考视频」那一档计价。

secondsstring | integer必填

时长秒数，字符串与整数都接受。

sizestring

如 1280x720。入站会拆成 resolution 与 aspect_ratio。

resolutionstring

480p / 720p / 1080p / 4k。

aspect_ratiostring

如 16:9、9:16。

fpsinteger

帧率。

generate_audioboolean

是否同时生成音轨（取决于模型是否支持）。

watermarkboolean

是否加水印。

seedinteger

随机种子，用于复现同一结果。

callback_urlstring

任务终态回调地址。给了它就不必轮询。

重复提交是安全的

带上 Idempotency-Key 请求头，重复提交会返回首次创建的那个任务，而不是再生成一条。

bash

curl https://ai.oceango.hk/v1/videos \  -H "Authorization: Bearer $AIROUTER_API_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: my-job-001" \  -d '{    "model": "doubao-seedance-1-0-pro",    "prompt": "A cat surfing a wave, cinematic",    "seconds": 5,    "resolution": "720p",    "aspect_ratio": "16:9"  }'

轮询状态#

创建接口返回的 id 就是任务号，用 GET /v1/videos/{id} 轮询到终态即可。

status	含义
`queued`	已排队，还没开始。此时可以取消。
`in_progress`	正在生成。
`completed`	完成，`content.video_url` 给出产物地址。
`failed`	失败，`error.code` 与 `error.message` 给出原因。

bash

curl https://ai.oceango.hk/v1/videos/$VIDEO_ID \  -H "Authorization: Bearer $AIROUTER_API_KEY"

响应里的 progress 是百分比进度（上游给出时才有）。建议轮询间隔从 2 秒起，别用 200 毫秒去打——它不会让视频更快生成，只会更早撞上限流。

Python：完整跑一遍，退避着轮询到终态

python

import os, time, requests
API = "https://ai.oceango.hk/v1"HEADERS = {"Authorization": f"Bearer {os.environ['AIROUTER_API_KEY']}"}
# 1. 创建任务，立刻拿到任务号（不是视频）task = requests.post(    API + "/videos",    headers=HEADERS,    json={"model": "volcengine/doubao-seedance", "prompt": "一只柴犬在维港边慢跑，电影感镜头"},    timeout=60,).json()
# 2. 轮询。间隔从 2 秒起逐步拉长，封顶 15 秒——#    打得再密视频也不会更快生成，只会更早撞上限流。delay = 2while True:    time.sleep(delay)    delay = min(delay * 1.5, 15)
    state = requests.get(API + "/videos/" + task["id"], headers=HEADERS, timeout=30).json()    if state["status"] == "completed":        print(state["content"]["video_url"])        break    if state["status"] == "failed":        raise RuntimeError(state["error"]["message"])    print(state["status"], state.get("progress", ""))

端点

说明

GET /v1/videos

列出当前 Key 所属用户的任务，支持 limit（1–100，默认 20）与 offset。

GET /v1/videos/{id}/content

302 重定向到产物地址，方便直接下载。

DELETE /v1/videos/{id}

取消任务。queued 可取消；已经在跑的返回 409。

计费#

按秒计费的模型，单价可能随分辨率分档，开音轨也可能另算——详情页显示的是实际生效的那一档。

创建任务时就会冻结一笔预扣。视频的预扣按估算的最终金额来，不像对话那样再乘 1.2；租约 60 分钟，任务还在跑就自动续期。

失败与取消的任务不收费，口径与对话端点一致，见计费口径。