Skip to main content
POST
/
v1
/
videos
创建视频任务
curl --request POST \
  --url https://models.rivus.cn/v1/videos \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form model=sora-2 \
  --form 'prompt=百事可乐宣传片' \
  --form seconds=4 \
  --form size=720x1280
{
  "id": "video_691209aab0a08198a4e78870277f7e3d0215e09cec47a737",
  "object": "video",
  "created_at": 1762789802,
  "status": "queued",
  "model": "sora-2",
  "prompt": "百事可乐宣传片",
  "progress": 0,
  "seconds": "4",
  "size": "720x1280"
}
使用 OpenAI Sora 模型生成视频内容。Rivus AI 支持完整的视频生成工作流，包括任务创建、状态查询和内容下载。

​
创建视频任务

通过提供文本提示词来生成视频： 
curl -X POST "https://models.rivus.cn/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -F "model=sora-2" \
  -F "prompt=百事可乐宣传片" \
  -F "seconds=10" \
  -F "size=720x1280"

​
请求参数

  • model：模型名称，支持 sora-2 和 sora-2-pro
  • prompt：视频生成的文本描述
  • seconds：视频时长（秒，字符串传递更兼容）。常见可用档位：
    • sora-2：10、15
    • sora-2-pro：15、25
    • OpenAI 官方 API 仅支持：4、8、12
  • size：视频分辨率，如 1280x720、1920x1080
时长选择建议：
  • 快速预览：优先 10 秒（若使用 OpenAI 官方 API，请按其仅支持的 4/8/12 秒档位）
  • 正式成片：sora-2-pro 的 25 秒可以呈现更完整叙事，但生成与下载时间也更长

​
响应示例

{
  "id": "video_691209aab0a08198a4e78870277f7e3d0215e09cec47a737",
  "object": "video",
  "created_at": 1762789802,
  "status": "queued",
  "model": "sora-2",
  "prompt": "百事可乐宣传片",
  "progress": 0,
  "seconds": "4",
  "size": "720x1280"
}

​
状态说明

任务创建后会经历以下状态：
  • queued：任务已排队，等待处理
  • processing：正在生成视频
  • completed：生成完成，可以下载视频
  • failed：生成失败
任务完成后，响应会包含 completed_at（完成时间）和 expires_at（过期时间）字段。视频文件会在过期时间后自动删除。

​
完整示例

创建任务并等待完成： 
# 1. 创建视频任务
RESPONSE=$(curl -X POST "https://models.rivus.cn/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -F "model=sora-2" \
  -F "prompt=百事可乐宣传片" \
  -F "seconds=10" \
  -F "size=720x1280")

VIDEO_ID=$(echo $RESPONSE | jq -r '.id')
echo "视频任务 ID: $VIDEO_ID"

# 2. 轮询查询状态
while true; do
  RESPONSE=$(curl "https://models.rivus.cn/v1/videos/$VIDEO_ID" \
    -H "Authorization: Bearer $TOKEN")
  
  STATUS=$(echo $RESPONSE | jq -r '.status')
  PROGRESS=$(echo $RESPONSE | jq -r '.progress')
  
  echo "当前状态: $STATUS (进度: $PROGRESS%)"
  
  if [ "$STATUS" = "completed" ]; then
    echo "✓ 视频生成完成"
    break
  elif [ "$STATUS" = "failed" ]; then
    echo "✗ 视频生成失败"
    exit 1
  fi
  
  sleep 5
done

# 3. 下载视频
curl -L "https://models.rivus.cn/v1/videos/$VIDEO_ID/content" \
  -H "Authorization: Bearer $TOKEN" \
  --output "${VIDEO_ID}.mp4"

echo "✓ 视频已保存到 ${VIDEO_ID}.mp4"
Rivus AI 会对不同供应商的返回结构进行统一封装，status 字段取值为 queued、processing、completed、failed 等。视频完成后会包含 completed_at 和 expires_at 时间戳。

​
脚本示例（Python，本地文件参考图）

仓库提供了基于 openai Python SDK 的本地验证脚本，可通过 input_reference 上传参考图并自动轮询与下载： 
export OPENAI_BASE_URL="https://models.rivus.cn/v1"
export OPENAI_API_KEY="$TOKEN"

python3 scripts/sora2_image_to_video_sdk.py \
  --prompt "百事可乐宣传片" \
  --seconds 4 \
  --size 720x1280 \
  --image /absolute/path/to/ref.jpg \
  --output sora_video.mp4

​
参考图生视频（Image-to-Video）

除纯文本生视频外，Rivus AI 也支持“带参考图”的视频生成。按照 OpenAI Sora 的接口规范，在创建任务时以 multipart/form-data 方式上传参考图文件字段 input_reference。

​
curl 示例（multipart）

curl -X POST "https://models.rivus.cn/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -F "model=sora-2" \
  -F "prompt=百事可乐宣传片，都市街拍风，年轻活力，镜头运动丰富" \
  -F "seconds=10" \
  -F "size=720x1280" \
  -F "input_reference=@/absolute/path/to/ref.jpg"
若通道为 OpenAI 官方 API，seconds 必须是 4、8 或 12 且需在 multipart 表单中显式提供。请确保 -F seconds=8 使用的是纯数字，不要加引号，也不要误用 Bash/Zsh 的保留变量 SECONDS。

​
Python SDK 示例（openai-python）

from openai import OpenAI

client = OpenAI(
    base_url="https://models.rivus.cn/v1",
    api_key="$TOKEN",
)

with open("./ref.jpg", "rb") as f:
    job = client.videos.create(
        model="sora-2",
        prompt="百事可乐宣传片，都市街拍风，年轻活力，镜头运动丰富",
        seconds="10",         # 以字符串传递更兼容
        size="720x1280",
        input_reference=f,     # 关键：参考图文件
    )

print("任务ID:", job.id, "状态:", job.status)

# 轮询
import time
while True:
    cur = client.videos.retrieve(job.id)
    print("状态:", cur.status, "进度:", getattr(cur, "progress", None))
    if cur.status in ("completed", "failed"):
        job = cur
        break
    time.sleep(2)

if job.status == "completed":
    content = client.videos.download_content(job.id)
    content.write_to_file("output.mp4")
    print("已保存到 output.mp4")
else:
    print("生成失败:", getattr(job, "error", None))
本仓库已提供两个可执行脚本便于本地验证：
  • curl 版本：scripts/validate_image2video.sh（自动下载示例参考图、轮询并下载成片）
  • SDK 版本：scripts/sora2_image_to_video_sdk.py（基于 openai Python SDK，支持 --image/--seconds/--size 参数）

Authorizations

​
Authorization
string
header
required

使用 API Key 作为 Bearer Token

Body

multipart/form-data
​
model
enum<string>
required

模型名称

Available options:
sora-2,
sora-2-pro
Example:

"sora-2"

​
prompt
string
required

视频生成的文本描述，最多 1000 个字符

Maximum string length: 1000
Example:

"百事可乐宣传片"

​
seconds
enum<integer>

视频时长（秒）。sora-2 支持 4、8、10、12、15 秒，默认 10；sora-2-pro 支持 4、8、12、15、25 秒，默认 15

Available options:
4,
8,
10,
12,
15,
25
Example:

4

​
size
enum<string>
default:1280x720

视频分辨率

Available options:
1280x720,
1920x1080,
720x1280,
1080x1920
Example:

"720x1280"

Response

任务创建成功

​
id
string

视频任务的唯一标识符

Example:

"video_691209aab0a08198a4e78870277f7e3d0215e09cec47a737"

​
object
enum<string>

对象类型

Available options:
video
Example:

"video"

​
created_at
integer

创建时间戳（Unix 时间）

Example:

1762789802

​
completed_at
integer

任务完成时间戳（仅在 completed 状态下存在）

Example:

1762789891

​
expires_at
integer

视频过期时间戳（仅在 completed 状态下存在）

Example:

1762793491

​
model
string

使用的模型名称

Example:

"sora-2"

​
status
enum<string>

任务状态

Available options:
queued,
processing,
completed,
failed
Example:

"queued"

​
prompt
string

生成视频的文本描述

Example:

"一个无人机从海滩升空拍摄夕阳"

​
progress
integer

处理进度（0-100）

Required range: 0 <= x <= 100
Example:

0

​
seconds
string

视频时长（字符串格式）

Example:

"10"

​
size
string

视频分辨率

Example:

"1280x720"

​
assets
object[]

生成的视频资源数组，仅在 completed 状态下存在（部分供应商可能不返回此字段，需通过 /content 端点下载）

​
parent_video_id
string

父视频 ID（仅 Remix 任务返回）

Example:

"video_691209aab0a08198a4e78870277f7e3d0215e09cec47a737"

​
error
object

错误信息，仅在 failed 状态下存在