视频生成概述与通用流程

视频生成都是异步任务:提交接口只返回任务 ID,成片要轮询查询接口拿到。提交响应里没有视频文件。

项 值
提交 POST /v1/video/generations
查询 GET /v1/video/generations/{task_id}
鉴权 Authorization: Bearer YOUR_API_KEY
Content-Type application/json(也接受 multipart/form-data)

最短路径

BASH
# 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。 这条规则对所有厂商、两套入口都成立,照抄即可:

PYTHON
task_id = resp.get("id") or resp.get("task_id")
JAVASCRIPT
const taskId = resp.id ?? resp.task_id;

提交请求的 HTTP 状态码非 200 时没有任务 ID,响应是错误体(见「错误」)。

查询响应

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

JSON
{
  "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。

PYTHON
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 对象不同:

JSON
{ "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

相关文档