OpenAI 兼容-Videos

按 OpenAI Videos API 的格式生成视频:提交拿到 id,轮询到 completed,再下载成片。适合直接用 OpenAI SDK 接入 Sora 等模型。

项 值
提交 POST /v1/videos
查询 GET /v1/videos/{video_id}
下载 GET /v1/videos/{video_id}/content
鉴权 Authorization: Bearer YOUR_API_KEY(三个端点都带)
Content-Type multipart/form-data(推荐,与官方 SDK 一致)或 application/json

异步任务流程、计费与状态说明见 概述与通用流程。

快速示例

Python(OpenAI SDK)

PYTHON
import os, time
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEXTAI_API_KEY"],
    base_url="https://www.nextai-code.com/v1",
)

video = client.videos.create(
    model="grok-imagine-video-1.5",
    prompt="A calico cat playing a piano on stage",
    size="1280x720",
    seconds="8",
)

while video.status not in ("completed", "failed", "cancelled"):
    time.sleep(15)
    video = client.videos.retrieve(video.id)

if video.status == "completed":
    client.videos.download_content(video.id).write_to_file("output.mp4")
else:
    print("failed:", video.error)

SDK 会自动以 multipart 提交,并在三个请求上都带 API Key。

cURL

BASH
# 提交
curl https://www.nextai-code.com/v1/videos \
  -H "Authorization: Bearer $NEXTAI_API_KEY" \
  -F "model=grok-imagine-video-1.5" \
  -F "prompt=A calico cat playing a piano on stage" \
  -F "size=1280x720" \
  -F "seconds=8"

# 查询
curl https://www.nextai-code.com/v1/videos/video_abc123 \
  -H "Authorization: Bearer $NEXTAI_API_KEY"

# 下载
curl -L https://www.nextai-code.com/v1/videos/video_abc123/content \
  -H "Authorization: Bearer $NEXTAI_API_KEY" \
  -o output.mp4

Node.js

JAVASCRIPT
import fs from 'node:fs';

const BASE = 'https://www.nextai-code.com/v1';
const headers = { Authorization: `Bearer ${process.env.NEXTAI_API_KEY}` };

const form = new FormData();
form.append('model', 'grok-imagine-video-1.5');
form.append('prompt', 'A futuristic city at night');
form.append('size', '1280x720');
form.append('seconds', '8');

const submit = await fetch(`${BASE}/videos`, { method: 'POST', headers, body: form });
let video = await submit.json();
if (!submit.ok) throw new Error(video.message ?? JSON.stringify(video));

while (!['completed', 'failed', 'cancelled'].includes(video.status)) {
  await new Promise((r) => setTimeout(r, 15000));
  video = await (await fetch(`${BASE}/videos/${video.id}`, { headers })).json();
}

if (video.status === 'completed') {
  const res = await fetch(`${BASE}/videos/${video.id}/content`, { headers });
  if (!res.ok) throw new Error(JSON.stringify(await res.json()));
  fs.writeFileSync('output.mp4', Buffer.from(await res.arrayBuffer()));
}

FormData 由运行时自动设置 multipart 边界,不要手动写 Content-Type。

请求参数

POST /v1/videos

参数 类型 必填 说明
model string 是 模型名,以模型列表返回为准。缺失返回 400 missing_model
prompt string 是 视频描述。缺失返回 400 missing_prompt,全为空白返回 400 invalid_request
size string 否 分辨率,如 1280x720。Sora 的可选值见下表;按规格计费的模型必须传
seconds string 否 时长(秒),如 "4"、"8"、"12"
input_reference file 否 参考图文件(仅 multipart),传了即为图生视频
其它字段 — 否 原样转给模型服务商,是否生效取决于模型

平台把请求体原样转给模型服务商,不改写字段。

Sora 尺寸

Sora 型号 可选 size 未传时
标准版 720x1280、1280x720 720x1280,4 秒
Pro 版 720x1280、1280x720、1792x1024、1024x1792 同上
  • 不在可选值内返回 400 invalid_size(size 参数不合法)。
  • Sora 按次计费时,费用随时长和尺寸增加(1792x1024 / 1024x1792 单价更高),以控制台模型价格页为准。
  • 尺寸校验与按时长计费都读取 multipart 的 size / seconds 字段,调用 Sora 请使用 multipart 提交。

其它兼容模型

除 Sora 外,其它兼容 OpenAI Videos 协议的模型(以 GET /v1/models 为准)也可通过本接口调用:

  • 请求体原样转给模型服务商,其要求的额外字段直接放在请求体里一起传。
  • 按规格计费的模型必须传能匹配价目的 size,见 概述 · 计费。

可灵、即梦、Vidu 也能用本接口提交,请求字段按 概述 · 统一请求字段 和各厂商页传。

响应

提交响应

JSON
{
  "id": "video_abc123",
  "object": "video",
  "model": "grok-imagine-video-1.5",
  "status": "queued",
  "progress": 0,
  "created_at": 1734567890,
  "seconds": "8",
  "size": "1280x720"
}
字段 类型 说明
id string 任务 ID,用于查询和下载
object string 固定为 video
model string 模型名
status string queued / in_progress / completed / failed,Sora 还可能为 cancelled(终态)
progress integer 0–100
created_at / completed_at / expires_at integer Unix 秒,有值才返回
seconds / size string 时长与尺寸
remixed_from_video_id string 有值才返回
error object 失败时为 { "message", "code" }

用本接口提交可灵、即梦、Vidu 时,提交响应同时带 id 和 task_id,status 为空字符串。任务 ID 统一按 概述 · 读取任务 ID 读取即可。

查询响应

GET /v1/videos/{video_id} 返回 OpenAI Video 对象,字段同上。各厂商差异:

厂商 返回 成片地址
Sora 等 OpenAI Videos 协议模型 Video 对象 用 下载成片 端点获取
可灵、即梦、Vidu Video 对象,另带 meta_data meta_data.url(模型服务商 CDN 直链)
Google Veo 与统一格式查询相同的结构,不是 Video 对象 见 Google Veo
豆包 Seedance 不支持,返回 501 not_implemented 请改用 GET /v1/video/generations/{task_id}

可灵、即梦、Vidu 的查询示例:

JSON
{
  "id": "866000000000000000",
  "object": "video",
  "model": "",
  "status": "completed",
  "progress": 100,
  "created_at": 1734567890,
  "completed_at": 1734568000,
  "seconds": "5",
  "meta_data": { "url": "https://cdn.example.com/video.mp4" }
}

此时 status 可能为 queued、in_progress、completed、failed,或 unknown(状态尚未同步,继续轮询)。

任务状态每 15 秒左右刷新一次,轮询间隔建议 10~15 秒。

下载成片

GET /v1/videos/{video_id}/content 返回视频二进制流,请求时带 Authorization: Bearer YOUR_API_KEY。

  • 仅适用于 Sora 等 OpenAI Videos 协议模型。可灵、即梦、Vidu、豆包 Seedance 的成片是模型服务商 CDN 直链,请直接下载查询结果里的地址。
  • 任务未完成时返回 400,请在 status 为 completed 后再下载。
  • 成片在模型服务商处有有效期,拿到后请尽快转存。

下载端点的错误为 OpenAI 格式 {"error": {"message": "...", "type": "..."}}:

HTTP message
400 任务尚未完成,当前状态:...
404 任务不存在
502 获取视频内容失败 或 服务返回状态码 xxx,可稍后重试

错误

提交和查询的错误为扁平结构 {"code": "...", "message": "...", "data": null}。

HTTP code 说明
400 missing_model / missing_prompt 缺少 model / prompt
400 invalid_request prompt 全为空白
400 invalid_json / invalid_multipart_form 请求体无法解析(JSON 中 duration 必须是整数)
400 invalid_size Sora 尺寸不在可选值内
400 pricing_not_configured 模型暂未开放,或 size 未匹配任何价目
模型服务商的状态码 fail_to_fetch_task 模型服务商拒绝了提交,message 为其原始响应
500 invalid_response 模型服务商未返回任务 ID
501 not_implemented 该任务不支持 OpenAI 格式查询(豆包 Seedance)

通用任务错误见 概述 · 错误,鉴权等错误见 错误码。

相关文档