> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openp.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 视频生成(Sora)

> POST /v1/videos —— 文生视频

通过 Sora 生成视频。采用 **异步任务** 流程:提交后获取任务 ID,轮询完成后下载视频。

## 提交任务

```bash theme={null}
curl https://openp.ai/v1/videos \
  -H "Authorization: Bearer $OPENPAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "A red panda surfing on a giant wave at sunset, cinematic, 4K",
    "seconds": 8,
    "size": "1280x720"
  }'
```

### 参数

| 字段                | 类型      |  必填 | 说明                             |
| ----------------- | ------- | :-: | ------------------------------ |
| `model`           | string  |  ✅  | `sora-2` / `sora-2-pro` 等      |
| `prompt`          | string  |  ✅  | 视频描述                           |
| `seconds`         | integer |     | 时长(秒),典型 5-20                  |
| `size`            | string  |     | 分辨率,如 `1280x720` / `1920x1080` |
| `aspect_ratio`    | string  |     | `16:9` / `9:16` / `1:1`        |
| `n`               | integer |     | 生成数量(部分支持)                     |
| `input_reference` | object  |     | 输入参考图或视频                       |

## 响应(任务创建)

```json theme={null}
{
  "id": "video_01...",
  "object": "video.task",
  "status": "queued",
  "created_at": 1715750400,
  "model": "sora-2"
}
```

## 查询任务状态

```bash theme={null}
curl https://openp.ai/v1/videos/video_01... \
  -H "Authorization: Bearer $OPENPAI_API_KEY"
```

```json theme={null}
{
  "id": "video_01...",
  "status": "completed",
  "video_url": "https://...mp4",
  "thumbnail_url": "https://...jpg",
  "duration": 8,
  "created_at": 1715750400,
  "completed_at": 1715750460
}
```

`status` 可能值:`queued` / `processing` / `completed` / `failed`。

## 轮询建议

* 初始延迟 5-10 秒后开始轮询。
* 间隔 10-30 秒一次。
* 通常 1-5 分钟完成。
* 失败时 `failure_reason` 字段说明原因。

## 计费

按 **生成秒数 + 分辨率** 一笔固定扣费。
系统侧失败的任务不扣费;被上游拒绝的任务按已消耗算力扣费。