Sora 2 - Artifex API 文档

视频 Sora 2VIP

OpenAI Sora 2 · 12 秒高质量视频 · 文生 / 图生 · 异步任务

🎬 Sora 2 支持文生视频和图生视频，固定 12 秒时长，按次计费 $0.9/次。提交后异步轮询获取结果。

调用流程

Sora 2 采用异步任务模式：提交任务 → 轮询状态 → 获取视频

Step 1 · 提交任务

端点：POST /v1/videos

curl -X POST https://artifex.help/v1/videos \
  -H "Authorization: Bearer YOUR_VIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "a golden retriever puppy running through a field of sunflowers, slow motion, sunny afternoon",
    "aspect_ratio": "16:9",
    "duration": 12
  }'

立即返回：

{
  "id": "v_8c7e4b...",
  "task_id": "v_8c7e4b...",
  "object": "video",
  "status": "queued",
  "progress": 0,
  "video_url": null,
  "model": "sora-2"
}

Step 2 · 轮询状态

端点：GET /v1/videos/{id}

curl https://artifex.help/v1/videos/v_8c7e4b... \
  -H "Authorization: Bearer YOUR_VIP_API_KEY"

完成响应：

{
  "id": "v_8c7e4b...",
  "object": "video",
  "status": "completed",
  "progress": 100,
  "video_url": "https://...generated.mp4",
  "completed_at": 1714200180,
  "aspect_ratio": "16:9",
  "duration": 12
}

状态说明

status	含义	该做什么
`queued`	排队中	继续轮询
`in_progress`	生成中（progress 0–99）	继续轮询
`completed`	完成	取 `video_url`（mp4 直链）
`failed`	失败	查看 `error.message`

图生视频示例

通过 image 字段传入图片 URL 作为首帧参考：

curl -X POST https://artifex.help/v1/videos \
  -H "Authorization: Bearer YOUR_VIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "the character in the photo turns slowly toward the camera and smiles, soft cinematic lighting",
    "duration": 12,
    "aspect_ratio": "9:16",
    "image": "https://your-cdn.com/portrait.jpg"
  }'

Python 完整示例

import requests, time

BASE = "https://artifex.help"
KEY  = "YOUR_VIP_API_KEY"
H = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}

# Step 1: 提交
res = requests.post(f"{BASE}/v1/videos", headers=H, json={
    "model": "sora-2",
    "prompt": "a cat wearing an astronaut helmet floating in space",
    "aspect_ratio": "16:9",
    "duration": 12
}).json()

task_id = res["id"]
print(f"Task submitted: {task_id}")

# Step 2: 轮询
while True:
    time.sleep(10)
    status = requests.get(f"{BASE}/v1/videos/{task_id}", headers=H).json()
    print(f"Status: {status['status']} Progress: {status.get('progress', 0)}%")
    if status["status"] == "completed":
        print("Video URL:", status["video_url"])
        break
    elif status["status"] == "failed":
        print("Failed:", status.get("error"))
        break

提交字段

字段	类型	必填	说明
`model`	string	✅	`sora-2`
`prompt`	string	✅*	prompt 或 image 至少一项
`aspect_ratio`	string	❌	`16:9` / `9:16`，默认 16:9
`duration`	int	❌	固定 `12` 秒
`image`	string \| array	❌	图片 URL（首帧参考）

响应字段

字段	类型	说明
`id` / `task_id`	string	任务 ID（双字段兼容）
`status`	string	queued / in_progress / completed / failed
`progress`	int	0–100
`video_url`	string \| null	完成时为 mp4 直链
`completed_at`	int	完成时间戳
`error`	object	失败时返回 {message, code}

💡 Sora 2 按次计费 $0.9/次，提交即扣费。生成通常需要 60~180 秒。

⚠️ 需要使用 vip 分组的 API Key。普通 token 调用会返回 403。