视频生成¶

视频生成 API 提供了创建、查询、下载和删除视频生成任务的接口。

Sora 模型提供两种渠道，通过令牌分组区分：

渠道	令牌分组	模型名称	Content-Type	视频获取方式
官转渠道	`default`	`sora-2`、`sora-2-pro`	JSON 或 multipart	通过 `/content` 接口下载
逆向渠道	`Mini`	`sora-2`、`sora-2-pro`	JSON 或 multipart	通过 `/content` 接口下载

渠道选择说明

令牌分组选择 default → 使用官转渠道
令牌分组选择 Mini → 使用逆向渠道，调用方式与官转渠道几乎一致，唯一区别是 seconds 参数支持 "10" 或 "15"

创建视频¶

根据给定的提示生成视频响应。

POST /v1/videos

Authorizations¶

参数	类型	位置	必填	说明
Authorization	string	header	是	身份验证标头格式为 `Bearer <API_KEY>`，其中 `<API_KEY>` 是您的API令牌。

Body¶

官转渠道（default 分组）逆向渠道（Mini 分组）其他模型

支持两种模式：文生视频（JSON） 和 图生视频（multipart/form-data）。

文生视频（`application/json`）¶

参数	类型	必填	说明
model	string	是	`sora-2` 或 `sora-2-pro`
prompt	string	是	视频描述
seconds	string	否	视频时长：`"4"` / `"8"` / `"12"`
size	string	否	视频尺寸：`720x1280` / `1280x720` / `1024x1792` / `1792x1024`
callback_url	string	否	回调地址

图生视频（`multipart/form-data`）¶

使用参考图作为视频首帧，通过 multipart/form-data 上传。

参数	类型	必填	说明
model	string (form field)	是	`sora-2` 或 `sora-2-pro`
prompt	string (form field)	是	视频描述
seconds	string (form field)	否	视频时长：`"4"` / `"8"` / `"12"`
size	string (form field)	否	视频尺寸：`720x1280` / `1280x720` / `1024x1792` / `1792x1024`
input_reference	file (binary)	是	参考图文件，支持 JPEG / PNG / WebP

参考图尺寸要求

参考图尺寸**必须与 size 完全匹配**（如 size=1280x720 则图片必须为 1280×720），否则 API 返回 Unable to process image bytes 错误。建议上传前先 resize。

令牌分组选择 Mini 即可使用此渠道。调用方式与官转渠道一致，支持文生视频和图生视频，唯一区别是 seconds 参数支持的值不同。

文生视频（`application/json`）¶

参数	类型	必填	说明
model	string	是	`sora-2` 或 `sora-2-pro`
prompt	string	是	视频描述
seconds	string	否	视频时长：`"10"` / `"15"`
size	string	否	视频尺寸：`720x1280` / `1280x720` / `1024x1792` / `1792x1024`
callback_url	string	否	回调地址

图生视频（`multipart/form-data`）¶

参数	类型	必填	说明
model	string (form field)	是	`sora-2` 或 `sora-2-pro`
prompt	string (form field)	是	视频描述
seconds	string (form field)	否	视频时长：`"10"` / `"15"`
size	string (form field)	否	视频尺寸：`720x1280` / `1280x720` / `1024x1792` / `1792x1024`
input_reference	file (binary)	是	参考图文件，支持 JPEG / PNG / WebP

参考图尺寸要求

参考图尺寸**必须与 size 完全匹配**，否则 API 返回错误。建议上传前先 resize。

与官转渠道的区别

seconds 参数支持 "10" 或 "15"（官转为 "4" / "8" / "12"）
其余参数、请求方式、响应格式均与官转渠道一致

其他模型可使用 application/json 格式。

参数	类型	必填	说明
model	string	是	模型名称。例如：`kling_video`、`luma_video`、`runway_video` 等
prompt	string	是	视频生成的提示词描述
callback_url	string	否	任务完成后的回调通知URL
metadata	object	否	其他参数，可将官方的参数完整放进这个对象中（会覆盖外层同名参数）

Response¶

官转 / 逆向渠道其他模型

queued 阶段返回 8 个基础字段（官转渠道与逆向渠道响应格式一致）：

参数	类型	说明
id	string	任务 ID，如 `video_xxx`
object	string	固定 `"video"`
model	string	使用的模型
status	string	初始为 `"queued"`
progress	integer	初始为 `0`
created_at	integer	创建时间戳
seconds	string	视频时长
size	string	视频尺寸

参数	类型	说明
id	string	任务ID
object	string	对象类型
created_at	integer	创建时间
status	string	任务状态

请求示例¶

官转 - 文生视频官转 - 图生视频逆向渠道（Mini 分组）其他模型

curl -X POST https://cdn.12ai.org/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "一只可爱的小猫在阳光下玩耍",
    "seconds": "4",
    "size": "1280x720"
  }'

# 注意：参考图尺寸必须与 size 完全匹配（此处为 1280x720）
curl -X POST https://cdn.12ai.org/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -F "model=sora-2" \
  -F "prompt=让图片中的角色在海边奔跑" \
  -F "seconds=4" \
  -F "size=1280x720" \
  -F "input_reference=@reference.jpg"

# 令牌分组选择 Mini，seconds 支持 "10" 或 "15"
curl -X POST https://cdn.12ai.org/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "一只可爱的小猫在阳光下玩耍",
    "seconds": "15",
    "size": "1280x720"
  }'

curl -X POST https://cdn.12ai.org/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling_video",
    "prompt": "美丽的日落场景",
    "callback_url": "https://example.com/notify"
  }'

响应示例¶

官转 / 逆向渠道其他模型

{
  "id": "video_xxx",
  "object": "video",
  "model": "sora-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1759938772,
  "seconds": "4",
  "size": "1280x720"
}

{
  "id": "task_1234567890",
  "object": "video",
  "created_at": 1759938772,
  "status": "queued"
}

查询视频状态¶

查询视频生成任务状态。

GET /v1/videos/{id}

Authorizations¶

参数	类型	位置	必填	说明
Authorization	string	header	是	身份验证标头格式为 `Bearer <API_KEY>`，其中 `<API_KEY>` 是您的API令牌。

Path Parameters¶

参数	类型	必填	说明
id	string	是	任务ID

状态流转¶

queued → in_progress → completed / failed

Response¶

官转 / 逆向渠道其他模型

未完成时（`queued` / `in_progress`）¶

返回与创建响应相同的 8 个基础字段。

参数	类型	说明
id	string	任务 ID
object	string	固定 `"video"`
model	string	使用的模型
status	string	`"queued"` 或 `"in_progress"`
progress	integer	完成前为 `0`，完成时为 `100`
created_at	integer	创建时间戳
seconds	string	视频时长
size	string	视频尺寸

完成时（`completed`）¶

在基础字段之上，额外返回以下字段：

参数	类型	说明
prompt	string	原始提示词
error	null	无错误时为 `null`
completed_at	integer	完成时间戳
expires_at	integer	过期时间戳（约完成后 24 小时）
remixed_from_video_id	null	为 `null`

重要

查询接口**不返回 video_url**，必须通过 /v1/videos/{id}/content 接口下载视频。

参数	类型	说明
id	string	任务ID
object	string	对象类型
created_at	integer	创建时间
status	string	任务状态：`queued`、`in_progress`、`completed`、`failed`

请求示例¶

curl https://cdn.12ai.org/v1/videos/{id} \
  -H "Authorization: Bearer $API_KEY"

响应示例¶

官转 - 进行中官转 - 已完成

{
  "id": "video_xxx",
  "object": "video",
  "model": "sora-2",
  "status": "in_progress",
  "progress": 0,
  "created_at": 1759938772,
  "seconds": "4",
  "size": "1280x720"
}

{
  "id": "video_xxx",
  "object": "video",
  "model": "sora-2",
  "status": "completed",
  "progress": 100,
  "created_at": 1759938772,
  "seconds": "4",
  "size": "1280x720",
  "prompt": "一只可爱的小猫在阳光下玩耍",
  "error": null,
  "completed_at": 1759938832,
  "expires_at": 1760025232,
  "remixed_from_video_id": null
}

下载视频文件¶

获取已完成视频的 mp4 文件流。官转渠道和逆向渠道均通过此接口下载。

GET /v1/videos/{id}/content

Authorizations¶

参数	类型	位置	必填	说明
Authorization	string	header	是	身份验证标头格式为 `Bearer <API_KEY>`，其中 `<API_KEY>` 是您的API令牌。

Path Parameters¶

参数	类型	必填	说明
id	string	是	任务ID，如 `video_xxx`

Response¶

成功：Content-Type: video/mp4，body 为 mp4 文件流
失败：Content-Type: application/json，body 为错误 JSON

请求示例¶

curl -o output.mp4 https://cdn.12ai.org/v1/videos/video_xxx/content \
  -H "Authorization: Bearer $API_KEY"

删除视频¶

删除视频生成任务。

DELETE /v1/videos/{id}

Authorizations¶

参数	类型	位置	必填	说明
Authorization	string	header	是	身份验证标头格式为 `Bearer <API_KEY>`，其中 `<API_KEY>` 是您的API令牌。

Path Parameters¶

参数	类型	必填	说明
id	string	是	任务ID

Response¶

200 - 成功响应¶

参数	类型	说明
message	string	消息
success	boolean	是否成功

400 - 任务不存在¶

参数	类型	说明
error.message	string	错误消息

请求示例¶

curl -X DELETE https://cdn.12ai.org/v1/videos/video_xxx \
  -H "Authorization: Bearer $API_KEY"

响应示例¶

成功失败

{
  "message": "Task deleted successfully",
  "success": true
}

{
  "error": {
    "message": "Invalid request, Task not found"
  }
}

调用流程¶

官转渠道与逆向渠道（Mini 分组）调用流程一致：

POST /v1/videos            → 拿到任务 ID（video_xxx）
         ↓
GET /v1/videos/{id}         × N（每 3 秒轮询，直到 status == "completed"）
         ↓
GET /v1/videos/{id}/content → 保存 mp4 文件

完整调用示例¶

官转 - 文生视频 (cURL)官转 - 图生视频 (cURL)逆向渠道 Mini (cURL)官转 - Python

# 1. 创建视频任务（JSON）
curl -X POST https://cdn.12ai.org/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "一只可爱的小猫在阳光下玩耍",
    "seconds": "4",
    "size": "1280x720"
  }'
# 返回: {"id":"video_xxx","status":"queued",...}

# 2. 轮询任务状态（重复执行直到 status 为 completed）
curl https://cdn.12ai.org/v1/videos/video_xxx \
  -H "Authorization: Bearer $API_KEY"
# 返回: {"status":"completed","progress":100,...}

# 3. 下载视频文件
curl -o output.mp4 https://cdn.12ai.org/v1/videos/video_xxx/content \
  -H "Authorization: Bearer $API_KEY"

# 1. 创建视频任务（multipart/form-data，附带参考图）
# 注意：参考图尺寸必须与 size 完全匹配（此处为 1280x720）
curl -X POST https://cdn.12ai.org/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -F "model=sora-2" \
  -F "prompt=让图片中的角色在海边奔跑" \
  -F "seconds=4" \
  -F "size=1280x720" \
  -F "input_reference=@reference.jpg"
# 返回: {"id":"video_xxx","status":"queued",...}

# 2. 轮询 & 3. 下载（与文生视频相同）
curl https://cdn.12ai.org/v1/videos/video_xxx \
  -H "Authorization: Bearer $API_KEY"

curl -o output.mp4 https://cdn.12ai.org/v1/videos/video_xxx/content \
  -H "Authorization: Bearer $API_KEY"

# 1. 创建视频任务（Mini 分组令牌，seconds 支持 "10" 或 "15"）
curl -X POST https://cdn.12ai.org/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "一只可爱的小猫在阳光下玩耍",
    "seconds": "15",
    "size": "1280x720"
  }'
# 返回: {"id":"video_xxx","status":"queued",...}

# 2. 轮询任务状态（重复执行直到 status 为 completed）
curl https://cdn.12ai.org/v1/videos/video_xxx \
  -H "Authorization: Bearer $API_KEY"
# 返回: {"status":"completed","progress":100,...}

# 3. 下载视频文件
curl -o output.mp4 https://cdn.12ai.org/v1/videos/video_xxx/content \
  -H "Authorization: Bearer $API_KEY"

import time
import requests

API_KEY = "your-api-key"
BASE_URL = "https://cdn.12ai.org"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# 1. 创建视频任务
resp = requests.post(
    f"{BASE_URL}/v1/videos",
    headers=HEADERS,
    json={
        "model": "sora-2",
        "prompt": "一只可爱的小猫在阳光下玩耍",
        "seconds": "4",
        "size": "1280x720",
    },
)
video_id = resp.json()["id"]
print(f"任务已创建: {video_id}")

# 2. 轮询任务状态
while True:
    resp = requests.get(f"{BASE_URL}/v1/videos/{video_id}", headers=HEADERS)
    data = resp.json()
    status = data["status"]
    print(f"状态: {status}, 进度: {data['progress']}")

    if status == "completed":
        break
    elif status == "failed":
        print("任务失败")
        exit(1)

    time.sleep(3)

# 3. 下载视频文件（官转渠道通过 /content 接口）
resp = requests.get(f"{BASE_URL}/v1/videos/{video_id}/content", headers=HEADERS)
with open("output.mp4", "wb") as f:
    f.write(resp.content)
print("视频已保存为 output.mp4")

注意事项¶

官转渠道（default 分组）¶

prompt / error / completed_at / expires_at / remixed_from_video_id 仅在任务完成后才出现
progress 在整个过程中始终为 0，完成时直接跳为 100（无中间进度）
从 queued 到 completed 实测约 50～70 秒
expires_at 表示视频过期时间，约为完成后 24 小时，过期后 /content 接口将无法下载
查询接口**不返回 video_url**，必须通过 /v1/videos/{id}/content 接口下载
**图生视频**使用 input_reference 字段，必须通过 multipart/form-data 上传（不支持 JSON base64）
参考图尺寸**必须与 size 完全一致**，否则返回 Unable to process image bytes 错误
支持的参考图格式：JPEG、PNG、WebP
seconds 支持 "4" / "8" / "12"

逆向渠道（Mini 分组）¶

令牌分组选择 Mini 即可使用
调用方式、响应格式、下载流程与官转渠道完全一致
唯一区别：seconds 参数支持 "10" 或 "15"（官转为 "4" / "8" / "12"）

视频生成¶

创建视频¶

Authorizations¶

Body¶

文生视频（application/json）¶

图生视频（multipart/form-data）¶

文生视频（application/json）¶

图生视频（multipart/form-data）¶

Response¶

请求示例¶

响应示例¶

查询视频状态¶

Authorizations¶

Path Parameters¶

状态流转¶

Response¶

未完成时（queued / in_progress）¶

完成时（completed）¶

请求示例¶

响应示例¶

下载视频文件¶

Authorizations¶

Path Parameters¶

Response¶

请求示例¶

删除视频¶

Authorizations¶

Path Parameters¶

Response¶

200 - 成功响应¶

400 - 任务不存在¶

请求示例¶

响应示例¶

调用流程¶

完整调用示例¶

注意事项¶

官转渠道（default 分组）¶

逆向渠道（Mini 分组）¶

文生视频（`application/json`）¶

图生视频（`multipart/form-data`）¶

文生视频（`application/json`）¶

图生视频（`multipart/form-data`）¶

未完成时（`queued` / `in_progress`）¶

完成时（`completed`）¶