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)
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
# 提交
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
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 也能用本接口提交,请求字段按 概述 · 统一请求字段 和各厂商页传。
响应
提交响应
{
"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 的查询示例:
{
"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) |