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

# Sora 官方 API 转发方案（当前可用）

> 当前 Sora2 视频唯一可用线路：OpenAI Sora 官方 API 透明转发；创建令牌时仅支持 Sora2Official 或 GPTImage2 Enterprise 分组，并使用按量扣费。

## 方案介绍

<Info>
  当前 Sora2 视频新接入仅官方 API 转发可用。创建令牌规则与官方 API 转发 `gpt-image-2` 一致：只能选择 `Sora2Official` 或 `GPTImage2 Enterprise` 分组，并使用按量扣费。旧同步 API、旧异步队列、旧线路模型和角色创建文档已标为过时，仅供历史排查参考。
</Info>

**官方 API 转发**（官方 API 转发）是指直接调用 OpenAI 官方 Sora API 并透明转发给用户的方案。与已经过时的"旧线路"（官网旧线路）方案不同，官方 API 转发方案具有更高的稳定性和更精准的指令遵循能力。

<Info>
  **什么是官方 API 转发？**

  官方 API 转发是 OpenAI 官方 API 的透明转发服务。您的请求会直接转发到 OpenAI 官方服务器，享受与 OpenAI 官方完全一致的服务质量和稳定性。
</Info>

## 方案对比

| 对比项      | 官方 API 转发（当前可用） | 旧线路（已过时）         |
| -------- | --------------- | ---------------- |
| **稳定性**  | 官方 API 转发，稳定性更高 | 依赖旧线路，已不作为当前可用入口 |
| **指令遵循** | 精准还原            | 一般               |
| **画质**   | 稳定无模糊           | 偶现模糊             |
| **时长选择** | 4/8/12 秒        | 10/15 秒          |
| **图生视频** | 支持              | 支持               |
| **调用方式** | 仅异步             | 同步 + 异步          |
| **价格**   | 按秒计费            | 按次计费             |

<Tip>
  **如何选择？**

  * **当前新接入**：选择官方 API 转发方案
  * **旧线路文档**：仅用于历史排查，不建议新项目继续接入
</Tip>

## 支持的模型和定价

### sora-2（标准模型）

| 分辨率          | 每秒价格  | 4 秒   | 8 秒   | 12 秒  |
| ------------ | ----- | ----- | ----- | ----- |
| 720x1280（竖屏） | \$0.1 | \$0.4 | \$0.8 | \$1.2 |
| 1280x720（横屏） | \$0.1 | \$0.4 | \$0.8 | \$1.2 |

### sora-2-pro（高清模型）

| 分辨率             | 每秒价格  | 4 秒   | 8 秒   | 12 秒  |
| --------------- | ----- | ----- | ----- | ----- |
| 720x1280（竖屏）    | \$0.3 | \$1.2 | \$2.4 | \$3.6 |
| 1280x720（横屏）    | \$0.3 | \$1.2 | \$2.4 | \$3.6 |
| 1024x1792（竖屏高清） | \$0.5 | \$2.0 | \$4.0 | \$6.0 |
| 1792x1024（横屏高清） | \$0.5 | \$2.0 | \$4.0 | \$6.0 |

<Note>
  以上价格已包含本站服务费。
</Note>

## 如何开始使用

### 令牌创建规则

| 配置项     | 应该怎么选                                              | 说明                                                      |
| ------- | -------------------------------------------------- | ------------------------------------------------------- |
| 控制台入口   | [令牌管理](https://api2.laozhang.ai/token) → 新增令牌      | 建议为 Sora 官方 API 转发单独创建新令牌，不要复用旧 Sora2 旧线路令牌             |
| 计费模式    | **按量计费**（控制台显示为"按量优先"时选择"按量优先"）                    | 与官方 API 转发 `gpt-image-2` 一致，按实际官方 API 转发调用量扣费，不使用按次计费令牌 |
| 可选分组 1  | `Sora2Official`                                    | AZ + 官方密钥 混合官方 API 转发，普通 Sora 官方 API 转发接入优先选这个分组        |
| 可选分组 2  | `GPTImage2 Enterprise`                             | 官方密钥 API，适合更重视官方线路一致性和稳定性的生产调用                          |
| 不要选择    | 默认分组、`gpt-image-2-vip` 所在旧线路分组、旧 Sora2 旧线路/同步/异步分组 | 这些分组不是当前 Sora2 视频官方 API 转发入口                            |
| 请求里的模型名 | `sora-2` 或 `sora-2-pro`                            | 分组只决定线路和计费；视频生成请求仍在 `model` 字段传入 Sora 模型名               |

<Steps>
  <Step title="创建令牌">
    登录 [laozhang.ai 控制台](https://api2.laozhang.ai/token)，新增令牌，并按上表选择计费模式和分组。
  </Step>

  <Step title="配置计费模式">
    令牌计费模式必须选择 **"按量计费"**；如果控制台下拉框显示为"按量优先"，就选择"按量优先"。实际消费按官方 API 转发调用量扣费。

    <Warning>
      Sora 官方 API 转发方案不支持默认分组、旧线路分组或按次计费令牌。请不要选择默认分组、`gpt-image-2-vip` 所在旧线路分组，或其他旧线路分组。
    </Warning>
  </Step>

  <Step title="调用 API 生成视频">
    参考下方完整示例调用 API。
  </Step>
</Steps>

## API 参考

### 基础信息

| 配置项          | 值                                    |
| ------------ | ------------------------------------ |
| **Base URL** | `https://api2.laozhang.ai`           |
| **认证方式**     | `Authorization: Bearer YOUR_API_KEY` |
| **请求格式**     | `multipart/form-data`                |

### API 端点

| 端点                        | 方法   | 说明       |
| ------------------------- | ---- | -------- |
| `/v1/videos`              | POST | 创建视频生成任务 |
| `/v1/videos/{id}`         | GET  | 查询任务状态   |
| `/v1/videos/{id}/content` | GET  | 下载生成的视频  |

### 请求参数

| 参数                | 类型     | 必填 | 说明                              |
| ----------------- | ------ | -- | ------------------------------- |
| `model`           | string | 是  | 模型名称：`sora-2` 或 `sora-2-pro`    |
| `prompt`          | string | 是  | 视频描述文本                          |
| `size`            | string | 否  | 分辨率，如 `1280x720`（默认 `720x1280`） |
| `seconds`         | string | 否  | 视频时长：`4`、`8` 或 `12`（默认 `4`）     |
| `input_reference` | file   | 否  | 参考图片文件（用于图生视频）                  |

### 支持的分辨率（size 参数）

**sora-2:**

* `720x1280`（竖屏，默认）
* `1280x720`（横屏）

**sora-2-pro:**

* `720x1280`（竖屏）
* `1280x720`（横屏）
* `1024x1792`（竖屏高清）
* `1792x1024`（横屏高清）

## 完整示例

### 文生视频（cURL）

**Step 1: 创建视频生成任务**

```bash theme={null}
curl -X POST "https://api2.laozhang.ai/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F model="sora-2" \
  -F prompt="A golden retriever playing fetch on a sunny beach, waves gently rolling in the background, cinematic lighting" \
  -F size="1280x720" \
  -F seconds="8"
```

**响应示例：**

```json theme={null}
{
  "id": "video_69788dc4a1c8819887468fbeffdda023",
  "object": "video",
  "model": "sora-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1769508292,
  "size": "1280x720",
  "seconds": "8"
}
```

**Step 2: 轮询任务状态**

```bash theme={null}
curl "https://api2.laozhang.ai/v1/videos/video_69788dc4a1c8819887468fbeffdda023" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**响应示例（进行中）：**

```json theme={null}
{
  "id": "video_69788dc4a1c8819887468fbeffdda023",
  "object": "video",
  "status": "in_progress",
  "progress": 45,
  "created_at": 1769508292
}
```

**响应示例（完成）：**

```json theme={null}
{
  "id": "video_69788dc4a1c8819887468fbeffdda023",
  "object": "video",
  "status": "completed",
  "progress": 100,
  "created_at": 1769508292,
  "completed_at": 1769508592
}
```

**Step 3: 下载视频**

```bash theme={null}
curl "https://api2.laozhang.ai/v1/videos/video_69788dc4a1c8819887468fbeffdda023/content" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o output.mp4
```

### 图生视频（cURL）

<Info>
  **图生视频**功能允许您提供一张参考图片作为视频的第一帧，AI 会基于这张图片生成动态视频。
</Info>

```bash theme={null}
curl -X POST "https://api2.laozhang.ai/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F model="sora-2" \
  -F prompt="The camera slowly zooms in, the scene comes alive with gentle movement, cinematic atmosphere" \
  -F size="1280x720" \
  -F seconds="4" \
  -F input_reference="@your_image.jpeg;type=image/jpeg"
```

<Warning>
  **图片要求**

  * 图片分辨率必须与 `size` 参数匹配（如 size=1280x720，则图片需为 1280×720 像素）
  * 支持格式：JPEG、PNG、WebP
  * **不支持包含真人面孔的图片**（会被内容审核系统拒绝）
</Warning>

### Python 示例

```python theme={null}
import requests
import time

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api2.laozhang.ai"

headers = {
    "Authorization": f"Bearer {API_KEY}"
}

# 文生视频
def create_video(prompt, model="sora-2", seconds="8", size="1280x720"):
    response = requests.post(
        f"{BASE_URL}/v1/videos",
        headers=headers,
        data={
            "model": model,
            "prompt": prompt,
            "seconds": seconds,
            "size": size
        }
    )
    response.raise_for_status()
    return response.json()

# 图生视频
def create_video_from_image(prompt, image_path, model="sora-2", seconds="4", size="1280x720"):
    with open(image_path, "rb") as f:
        response = requests.post(
            f"{BASE_URL}/v1/videos",
            headers=headers,
            data={
                "model": model,
                "prompt": prompt,
                "seconds": seconds,
                "size": size
            },
            files={
                "input_reference": (image_path.split("/")[-1], f, "image/jpeg")
            }
        )
    response.raise_for_status()
    return response.json()

# 轮询任务状态
def poll_status(video_id, timeout=600, interval=15):
    start_time = time.time()
    while time.time() - start_time < timeout:
        response = requests.get(
            f"{BASE_URL}/v1/videos/{video_id}",
            headers=headers
        )
        response.raise_for_status()
        data = response.json()

        status = data.get("status")
        progress = data.get("progress", 0)
        print(f"状态: {status}, 进度: {progress}%")

        if status == "completed":
            return data
        elif status == "failed":
            raise Exception(f"视频生成失败: {data.get('error')}")

        time.sleep(interval)

    raise TimeoutError("视频生成超时")

# 下载视频
def download_video(video_id, output_path="output.mp4"):
    response = requests.get(
        f"{BASE_URL}/v1/videos/{video_id}/content",
        headers=headers
    )
    response.raise_for_status()

    with open(output_path, "wb") as f:
        f.write(response.content)
    print(f"视频已保存到: {output_path}")

# 完整流程示例
if __name__ == "__main__":
    # 文生视频
    job = create_video(
        prompt="A golden retriever playing fetch on a sunny beach",
        model="sora-2",
        seconds="8",
        size="1280x720"
    )
    print(f"任务已创建: {job['id']}")

    # 等待完成
    result = poll_status(job["id"])
    print("视频生成完成!")

    # 下载视频
    download_video(job["id"], "my_video.mp4")

    # 图生视频示例
    # job2 = create_video_from_image(
    #     prompt="The scene comes alive with gentle movement",
    #     image_path="reference.jpg",
    #     model="sora-2",
    #     seconds="4",
    #     size="1280x720"
    # )
```

### 任务状态说明

| 状态            | 说明           |
| ------------- | ------------ |
| `queued`      | 任务已加入队列，等待处理 |
| `in_progress` | 正在生成视频       |
| `completed`   | 生成完成，可下载     |
| `failed`      | 生成失败         |

<Tip>
  **轮询建议**

  视频生成通常需要 2-5 分钟。建议每 15-20 秒轮询一次状态，避免过于频繁的请求。
</Tip>

## 开发文档

官方 API 转发方案完全兼容 OpenAI 官方 API 格式，更多参数和高级用法请参考：

<CardGroup cols={2}>
  <Card title="OpenAI Sora 官方指南" icon="book-open" href="https://platform.openai.com/docs/guides/video-generation">
    视频生成完整指南
  </Card>

  <Card title="OpenAI Videos API" icon="code" href="https://platform.openai.com/docs/api-reference/videos">
    API 接口参考文档
  </Card>

  <Card title="Sora 2 模型文档" icon="cpu" href="https://platform.openai.com/docs/models/sora-2">
    sora-2 模型详情
  </Card>

  <Card title="Sora 2 Pro 模型文档" icon="sparkles" href="https://platform.openai.com/docs/models/sora-2-pro">
    sora-2-pro 模型详情
  </Card>
</CardGroup>

## 注意事项

<Warning>
  **重要限制**

  1. **仅支持异步调用**：官方 API 转发方案不支持同步 API，所有请求均为异步模式
  2. **仅支持按量扣费**：必须选择"按量计费"模式，不支持"按次计费"令牌
  3. **仅支持两个官方兼容分组**：创建令牌时只能选择 `Sora2Official` 或 `GPTImage2 Enterprise`
  4. **图片限制**：图生视频不支持包含真人面孔的图片
</Warning>

## 常见问题

<AccordionGroup>
  <Accordion title="官方 API 转发和旧线路有什么区别？">
    官方 API 转发是直接调用 OpenAI 官方 API 的透明转发；旧线路是历史阶段通过旧网站接入方式实现的旧线路，目前已不作为 Sora2 视频的新接入入口。
  </Accordion>

  <Accordion title="为什么官方 API 转发不支持同步 API？">
    OpenAI 官方 Sora API 本身只提供异步调用方式，因此官方 API 转发方案也仅支持异步调用。
  </Accordion>

  <Accordion title="为什么时长选项不同？">
    官方 API 转发方案支持 OpenAI 官方的 4/8/12 秒时长选项；旧线路方案支持的是官网界面的 10/15 秒时长。
  </Accordion>

  <Accordion title="图生视频对图片有什么要求？">
    图片分辨率必须与目标视频的 size 参数匹配。例如，如果设置 size=1280x720，则图片必须是 1280×720 像素。支持 JPEG、PNG、WebP 格式，不支持包含真人面孔的图片。
  </Accordion>
</AccordionGroup>