YL AI

Appearance

Videos ​

/v1/videos 是异步视频生成接口。发起创建请求后，服务会先返回一个视频任务对象；随后通过 GET /v1/videos/{video_id} 查询状态与进度；任务完成后再通过 GET /v1/videos/{video_id}/content 下载文件。

WARNING

视频接口是异步任务模式，不会像文本接口一样直接返回最终内容。

请求地址 ​

  • 创建任务：POST https://huobaoapi.com/v1/videos
  • 查询进度：GET https://huobaoapi.com/v1/videos/{video_id}
  • 下载内容：GET https://huobaoapi.com/v1/videos/{video_id}/content

创建视频任务 ​

常用请求字段 ​

字段必填说明
prompt是视频生成提示词
model否视频模型，常用 sora-2 或 sora-2-pro，默认 sora-2
seconds否视频时长，可选 4、8、12，默认 4
size否分辨率，可选 720x1280、1280x720、1024x1792、1792x1024，默认 720x1280
input_reference否参考图对象，传 image_url 或 file_id 二选一

cURL 示例 ​

bash
curl https://huobaoapi.com/v1/videos \
  -H "Authorization: Bearer sk-xxxxxxxxxxxx" \
  -F "model=sora-2" \
  -F "prompt=A calico cat playing a piano on stage" \
  -F "seconds=8" \
  -F "size=1280x720"

Node.js SDK 示例 ​

javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-xxxxxxxxxxxx",
  baseURL: "https://huobaoapi.com/v1",
});

const video = await client.videos.create({
  model: "sora-2",
  prompt: "A calico cat playing a piano on stage",
  seconds: "8",
  size: "1280x720",
});

console.log(video);

创建成功返回示例 ​

json
{
  "id": "video_123",
  "object": "video",
  "model": "sora-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1712697600,
  "size": "1280x720",
  "seconds": "8",
  "quality": "standard"
}

查询视频任务进度 ​

建议轮询间隔为 10 到 20 秒。progress 为近似进度百分比，status 为任务状态。

常见返回字段 ​

字段说明
id视频任务 ID
object固定为 video
status任务状态：queued、in_progress、completed、failed
progress近似完成百分比
created_at任务创建时间，Unix 时间戳（秒）
completed_at任务完成时间，完成后返回
expires_at下载内容过期时间，返回下载资源时可能出现
prompt本次视频任务的提示词
error.code失败时的错误码
error.message失败时的错误描述

进度返回示例 ​

排队中：

json
{
  "id": "video_123",
  "object": "video",
  "status": "queued",
  "progress": 0,
  "created_at": 1712697600,
  "model": "sora-2",
  "seconds": "8",
  "size": "1280x720"
}

处理中：

json
{
  "id": "video_123",
  "object": "video",
  "status": "in_progress",
  "progress": 33,
  "created_at": 1712697600,
  "model": "sora-2",
  "seconds": "8",
  "size": "1280x720"
}

已完成：

json
{
  "id": "video_123",
  "object": "video",
  "status": "completed",
  "progress": 100,
  "created_at": 1712697600,
  "completed_at": 1712697815,
  "expires_at": 1712701415,
  "model": "sora-2",
  "prompt": "A calico cat playing a piano on stage",
  "seconds": "8",
  "size": "1280x720"
}

失败：

json
{
  "id": "video_123",
  "object": "video",
  "status": "failed",
  "progress": 12,
  "created_at": 1712697600,
  "model": "sora-2",
  "seconds": "8",
  "size": "1280x720",
  "error": {
    "code": "invalid_reference_image",
    "message": "Input images with human faces are currently rejected."
  }
}

TIP

上面的已完成、失败示例是根据 OpenAI 官方返回字段整理的文档示例，具体字段组合和数值请以实际接口返回为准。

下载视频内容 ​

默认返回 MP4 视频内容，也支持通过 variant 查询不同下载内容：

参数说明
variant=video下载视频文件，默认值
variant=thumbnail下载缩略图
variant=spritesheet下载 spritesheet

下载视频 ​

bash
curl https://huobaoapi.com/v1/videos/video_123/content \
  -H "Authorization: Bearer sk-xxxxxxxxxxxx" \
  --output video.mp4

下载缩略图 ​

bash
curl "https://huobaoapi.com/v1/videos/video_123/content?variant=thumbnail" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxx" \
  --output thumbnail.webp

可选：Webhook 回调 ​

如果不想轮询，也可以配置 webhook 接收任务结果通知。OpenAI 官方文档中视频任务会触发以下事件：

  • video.completed
  • video.failed

示例回调：

json
{
  "id": "evt_abc123",
  "object": "event",
  "created_at": 1758941485,
  "type": "video.completed",
  "data": {
    "id": "video_abc123"
  }
}

参考文档 ​

YL AI

Copyright © 2024-present