sora 视频生成格式 - 数字先锋API文档

# sora 视频生成 API 文档
POST /v1/videos/generations
GET /v1/videos/generations/{TASK_ID}

sora 视频采用OpenAI官方接口

体验网址：https://try.cxsee.com/video/sora

## 1) 鉴权方式

- Header：
  - `Authorization: Bearer YOUR_API_KEY`
  - `Content-Type: application/json`

---

## 2) 创建视频任务

### 请求

`POST /v1/videos/generations`

#### cURL 示例
```bash
curl -sS 'https://api.cxsee.com/v1/videos/generations' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "model": "sora-2",
    "prompt": "电影级广角镜头，一位站在火星悬崖上的孤独宇航员，他正眺望着地平线上巨大而美丽的地球升起。",
    "duration": 6,
    "size": "1280x720"
  }'
```

### 请求参数

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 是 | 模型名，如 `sora-2-pro` |
| prompt | string | 是 | 视频提示词 |
| duration | integer | 否 | 期望时长（秒） |
| size | string | 否 | 分辨率，如 `1280x720` |

### 响应（示例）
> 实际字段以官方返回为准，通常会返回任务 ID。
```json
{
  "id": "video_xxx...",
  "status": "queued"
}
```

---

## 3) 查询任务状态

### 请求

`GET /v1/videos/generations/{TASK_ID}`

#### cURL 示例
```bash
TASK_ID="video_xxx"
API_KEY="YOUR_API_KEY"

curl -sS "https://api.cxsee.com/v1/videos/generations/${TASK_ID}" \
  -H "Authorization: Bearer ${API_KEY}" | jq .
```

---

## 4) 状态说明

你当前返回里可能出现两层状态：

- 顶层：`status`（如 `SUCCESS`）
- `data.status`（如 `queued` / `processing` / `completed` / `failed`）

### 建议以 `data.status` 为主判断：

| data.status | 含义 |
|---|---|
| queued | 排队中 |
| processing | 生成中 |
| completed | 已完成（可取视频 URL） |
| failed | 失败 |

---

## 5) 成功结果（重点）

当 `data.status = completed` 时，重点读这些字段：

- `data.video_url`：视频下载地址
- `data.url`：通常与 `video_url` 一致
- `data.thumbnail_url`：缩略图
- `data.spritesheet_url`：雪碧图（如有）
- `data.completed_at`：完成时间戳
- `data.expires_at`：资源过期时间戳（如有）

---

## 6) 真实查询结果的判定示例

你给的任务里：

- 顶层 `status = "SUCCESS"`
- `data.status = "completed"`
- `data.video_url` 有值

=> 任务已完成，可直接使用 `video_url`。

---

## 7) 错误处理建议

- HTTP 非 2xx：请求失败，按响应 body 记录错误。
- 2xx 但 `data.status=failed`：任务失败，读取错误字段（如 `data.error` / 顶层 `fail_reason`）。
- 建议轮询间隔：5~15 秒，避免高频请求。

---

上一篇：Responses API与Chat API对比下一篇：Responses（统一响应）