视频生成概述与通用流程
视频生成都是异步任务:提交接口只返回任务 ID,成片要轮询查询接口拿到。提交响应里没有视频文件。
| 项 | 值 |
|---|---|
| 提交 | POST /v1/video/generations |
| 查询 | GET /v1/video/generations/{task_id} |
| 鉴权 | Authorization: Bearer YOUR_API_KEY |
| Content-Type | application/json(也接受 multipart/form-data) |
最短路径
# 1. 提交,记下任务 ID(读取方法见「读取任务 ID」)
curl https://www.nextai-code.com/v1/video/generations \
-H "Authorization: Bearer $NEXTAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "YOUR_MODEL", "prompt": "宇航员在月球上慢慢站起身"}'
# 2. 每 10~15 秒查询一次,直到 data.status 为 SUCCESS 或 FAILURE
curl https://www.nextai-code.com/v1/video/generations/TASK_ID \
-H "Authorization: Bearer $NEXTAI_API_KEY"
# 3. SUCCESS 后,成片地址在 data.fail_reason(见「成片地址」)
可用模型以 模型列表(
GET /v1/models)返回为准。
两套入口
| 入口 | 提交 | 查询 | 适用 |
|---|---|---|---|
| 统一格式(推荐) | POST /v1/video/generations |
GET /v1/video/generations/{task_id} |
所有视频模型,查询响应结构统一 |
| OpenAI 兼容 | POST /v1/videos |
GET /v1/videos/{task_id} |
Sora 等 OpenAI Videos 协议模型;可灵、即梦、Vidu 也可用。详见 OpenAI 兼容-Videos |
两套入口的提交行为相同,区别只在查询响应的格式。豆包 Seedance 任务不支持 GET /v1/videos/{task_id}(返回 501),请用统一格式查询。
统一请求字段
POST /v1/video/generations 的请求体:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model |
string | 是 | 模型名 |
prompt |
string | 是 | 视频描述。为空或全为空白返回 400 invalid_request |
image |
string | 否 | 单张参考图(URL 或 Base64,见各厂商页)。传了即为图生视频 |
images |
string[] | 否 | 多张参考图。与 image 同时传时以 images 为准 |
size |
string | 否 | 规格。各厂商含义不同(可灵换算为宽高比,Vidu 作为分辨率),见各厂商页 |
duration |
integer | 否 | 时长(秒),必须是整数 |
mode |
string | 否 | 生成模式,仅可灵使用(std / pro) |
metadata |
object | 否 | 厂商专有参数,可用字段见各厂商页 |
使用 multipart/form-data 时,用 seconds 字段传时长;上表以外的表单字段会作为 metadata 处理(纯数字自动转为数值)。
Sora 等 OpenAI Videos 协议模型的请求体按 OpenAI 兼容-Videos 的字段传,上表映射不适用。
读取任务 ID
各厂商的提交响应结构不同:
| 厂商 | 提交响应 |
|---|---|
| 可灵、即梦、Vidu | {"id": "...", "task_id": "...", "object": "video", "model": "...", "created_at": ...} |
| Sora 等 OpenAI Videos 协议模型 | OpenAI Video 对象,只有 id,见 OpenAI 兼容-Videos |
| 豆包 Seedance、Google Veo | {"task_id": "..."} |
统一处理方法:先读 id,没有再读 task_id。 这条规则对所有厂商、两套入口都成立,照抄即可:
task_id = resp.get("id") or resp.get("task_id")
const taskId = resp.id ?? resp.task_id;
提交请求的 HTTP 状态码非 200 时没有任务 ID,响应是错误体(见「错误」)。
查询响应
GET /v1/video/generations/{task_id}:
{
"code": "success",
"message": "",
"data": {
"task_id": "TASK_ID",
"action": "textGenerate",
"status": "SUCCESS",
"fail_reason": "https://cdn.example.com/video.mp4",
"submit_time": 1734567890,
"start_time": 1734567900,
"finish_time": 1734568000,
"progress": "100%",
"data": {}
}
}
| 字段 | 说明 |
|---|---|
task_id |
任务 ID |
action |
任务类型(如 textGenerate、generate),仅供参考,不要依赖它判断业务逻辑 |
status |
任务状态,见下表 |
fail_reason |
成功时为成片地址,失败时为失败原因 |
submit_time / start_time / finish_time |
Unix 秒,未发生时为 0 |
progress |
进度字符串,如 "30%"、"100%" |
data |
模型服务商返回的原始任务数据,结构因厂商而异,仅供排查 |
Google Veo 的查询响应结构不同(data.status 为小写、成片在 data.url),见 Google Veo。下文「轮询示例」已同时兼容两种结构。
任务状态
status |
含义 | OpenAI 兼容格式对应 |
|---|---|---|
NOT_START |
已提交,状态尚未同步 | unknown |
SUBMITTED |
模型服务商已接收 | queued |
QUEUED |
排队中 | queued |
IN_PROGRESS |
生成中 | in_progress |
SUCCESS |
成功(终态) | completed |
FAILURE |
失败(终态) | failed |
终态只有 SUCCESS 和 FAILURE,其余状态继续轮询。
轮询示例
以下 Python 示例覆盖全部厂商:统一读取任务 ID、兼容 Veo 的查询结构、区分成片 URL 与 Data URI。
import base64, os, time, requests
BASE = "https://www.nextai-code.com/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['NEXTAI_API_KEY']}"}
def submit(body: dict) -> str:
r = requests.post(f"{BASE}/video/generations", headers=HEADERS, json=body, timeout=60)
resp = r.json()
if r.status_code != 200:
raise RuntimeError(f"{resp.get('code')}: {resp.get('message')}")
return resp.get("id") or resp.get("task_id")
def wait(task_id: str, interval: int = 15, timeout: int = 1800) -> str:
deadline = time.time() + timeout
while time.time() < deadline:
r = requests.get(f"{BASE}/video/generations/{task_id}", headers=HEADERS, timeout=120)
resp = r.json()
if r.status_code != 200:
raise RuntimeError(f"{resp.get('code')}: {resp.get('message')}")
data = resp["data"]
status = data["status"].upper() # Veo 返回小写
if status in ("SUCCESS", "SUCCEEDED"):
return data.get("url") or data.get("fail_reason") # Veo 用 url
if status in ("FAILURE", "FAILED"):
raise RuntimeError(f"任务失败:{data.get('fail_reason') or data.get('url')}")
time.sleep(interval)
raise TimeoutError(task_id)
def save(video: str, path: str = "output.mp4") -> None:
if video.startswith("data:"): # Veo:Data URI
content = base64.b64decode(video.split(",", 1)[1])
else:
# 平台地址(/v1/videos/{id}/content)带 API Key;
# 模型服务商的 CDN 直链不要带,避免把 API Key 发给第三方
headers = HEADERS if video.startswith(BASE) else {}
content = requests.get(video, headers=headers, timeout=300).content
with open(path, "wb") as f:
f.write(content)
task_id = submit({"model": "YOUR_MODEL", "prompt": "宇航员在月球上慢慢站起身"})
save(wait(task_id))
轮询建议:
- 任务状态每 15 秒左右刷新一次,轮询间隔建议 10~15 秒,更短也不会更快拿到结果。
- 生成耗时因模型而异,一般几分钟到十几分钟;请为整体等待设置上限(示例为 30 分钟)。
- 任务只能由提交它的同一账号查询,查不到返回
400 task_not_exist。 - 提交请求超时设 60 秒即可。
成片地址
平台不长期保存视频文件,成片地址来源如下:
| 厂商 | 成片地址 | 下载方式 |
|---|---|---|
| 可灵、即梦、Vidu、豆包 Seedance | 模型服务商的 CDN 直链 | 直接 GET,不要附带 API Key |
| Sora 等 OpenAI Videos 协议模型 | https://www.nextai-code.com/v1/videos/{task_id}/content |
带 Authorization: Bearer YOUR_API_KEY 下载,见 OpenAI 兼容-Videos |
| Google Veo | Data URI(data:video/mp4;base64,...) |
取逗号后的部分 Base64 解码 |
成片地址有有效期,过期后任务记录仍在但地址打不开。拿到地址后请尽快下载并转存到自己的存储。
计费
- 提交时预扣:提交成功即按模型价格预扣额度;余额不足返回
402 quota_not_enough,任务不会提交。 - 失败自动退还:任务最终为
FAILURE时,预扣额度自动退回。 - 按次计费:每次提交扣固定额度。
- 按规格计费:必须传能匹配价目的
size(或resolution),如720P、1280x720。不传或匹配不上返回400 pricing_not_configured。 - 按秒计费:同时传
duration和seconds时两者必须相等;都不传按 5 秒计;时长必须大于 0。 - 按 Token 计费(如豆包 Seedance):先按预估预扣,任务成功后按实际 Token 用量多退少补。
模型的计费方式和价格以控制台模型价格页为准。
错误
提交和查询接口的错误体为扁平结构,与对话接口的 error 对象不同:
{ "code": "invalid_request", "message": "prompt 不能为空", "data": null }
| HTTP | code |
说明 |
|---|---|---|
| 400 | invalid_request |
prompt 为空,或请求体无法解析 |
| 400 | invalid_multipart_form |
multipart 表单解析失败 |
| 400 | pricing_not_configured |
模型暂未开放,或按规格计费时 size 未匹配任何价目 |
| 400 | task_not_exist |
任务不存在或不属于当前账号 |
| 402 | quota_not_enough |
余额不足,请到控制台充值或在「API Keys」页调整额度 |
| 429 | — | 当前分组服务负载已饱和,请稍后再试,稍后重试 |
| 模型服务商的状态码 | fail_to_fetch_task |
模型服务商拒绝了提交,message 为其原始响应 |
| 500 | invalid_response |
模型服务商未返回任务 ID,可稍后重试 |
API Key 无效、模型不存在等在提交前被拦截的错误,返回 OpenAI 格式 {"error": {...}},见 错误码。
各厂商文档
| 厂商 | 文档 |
|---|---|
| OpenAI Sora 等 | OpenAI 兼容-Videos |
| 字节 豆包 Seedance | 豆包 Seedance |
| 快手 可灵 | 可灵 |
| 字节 即梦 | 即梦 |
| 生数 Vidu | Vidu |
| Google Veo | Google Veo |