> ## 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 Official API Forwarding Plan (Current)

> The only currently available Sora2 video route: OpenAI Sora official API forwarding; tokens must use the Sora2Official or GPTImage2 Enterprise group with usage-based billing.

## Introduction

<Info>
  New Sora2 video integrations currently use Official API Forwarding only. Token creation matches the official API forwarding `gpt-image-2` setup: select only `Sora2Official` or `GPTImage2 Enterprise`, and use usage-based billing. The old Sync API, old Async queue, legacy route models, and Character Creation docs are marked outdated for historical troubleshooting only.
</Info>

**Official API Forwarding** refers to the solution that directly calls OpenAI's official Sora API and transparently forwards it to users. Unlike the now-outdated "legacy route" solution, the Official API Forwarding plan offers higher stability and more precise instruction following.

<Info>
  **What is Official API Forwarding?**

  Official API Forwarding is a transparent forwarding service for OpenAI's official API. Your requests are directly forwarded to OpenAI's official servers, with service quality and stability aligned with OpenAI official.
</Info>

## Plan Comparison

| Aspect                    | Official API Forwarding (Current)             | Legacy Route (Outdated)                                                |
| ------------------------- | --------------------------------------------- | ---------------------------------------------------------------------- |
| **Stability**             | Official API forwarding with higher stability | Depends on legacy route integration and is no longer the current route |
| **Instruction Following** | Precise reproduction                          | Average                                                                |
| **Image Quality**         | Stable, no blur                               | Occasional blur                                                        |
| **Duration Options**      | 4/8/12 seconds                                | 10/15 seconds                                                          |
| **Image-to-Video**        | Supported                                     | Supported                                                              |
| **API Method**            | Async only                                    | Sync + Async                                                           |
| **Pricing**               | Per-second billing                            | Per-call billing                                                       |

<Tip>
  **How to choose?**

  * **New integrations**: Choose Official API Forwarding
  * **Legacy docs**: Use only for historical troubleshooting; do not start new projects on the old route
</Tip>

## Supported Models and Pricing

### sora-2 (Standard Model)

| Resolution           | Per Second | 4 sec | 8 sec | 12 sec |
| -------------------- | ---------- | ----- | ----- | ------ |
| 720×1280 (Portrait)  | \$0.1      | \$0.4 | \$0.8 | \$1.2  |
| 1280×720 (Landscape) | \$0.1      | \$0.4 | \$0.8 | \$1.2  |

### sora-2-pro (HD Model)

| Resolution               | Per Second | 4 sec | 8 sec | 12 sec |
| ------------------------ | ---------- | ----- | ----- | ------ |
| 720×1280 (Portrait)      | \$0.3      | \$1.2 | \$2.4 | \$3.6  |
| 1280×720 (Landscape)     | \$0.3      | \$1.2 | \$2.4 | \$3.6  |
| 1024×1792 (Portrait HD)  | \$0.5      | \$2.0 | \$4.0 | \$6.0  |
| 1792×1024 (Landscape HD) | \$0.5      | \$2.0 | \$4.0 | \$6.0  |

<Note>
  Prices above include our service fee.
</Note>

## How to Get Started

### Token Creation Rules

| Setting            | What to choose                                                                                      | Notes                                                                                                                            |
| ------------------ | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Console entry      | [Token Management](https://api2.laozhang.ai/token) → create a new token                             | Create a dedicated token for Sora Official API Forwarding; do not reuse a legacy Sora2 legacy-route token                        |
| Billing mode       | **Pay-as-you-go** (select "Quantity priority" if that is the console label)                         | Same as official API forwarding `gpt-image-2`; usage is deducted by actual official-forward consumption, not pay-per-call tokens |
| Supported group 1  | `Sora2Official`                                                                                     | Mixed AZ + official-key forwarding API; use this for normal Sora Official API Forwarding integrations                            |
| Supported group 2  | `GPTImage2 Enterprise`                                                                              | Pure official-key API for production calls that need stronger official-route consistency and stability                           |
| Do not select      | Default group, the legacy group used by `gpt-image-2-vip`, or legacy Sora2 legacy sync/async groups | These groups are not the current Sora2 video official-forward route                                                              |
| Request model name | `sora-2` or `sora-2-pro`                                                                            | The token group decides route and billing; the video request still passes the Sora model name in the `model` field               |

<Steps>
  <Step title="Create Token">
    Log in to [laozhang.ai console](https://api2.laozhang.ai/token), create a new token, and choose the billing mode and group according to the table above.
  </Step>

  <Step title="Configure Billing Mode">
    The token billing mode must be **"Pay-as-you-go"**. If the console dropdown shows "Quantity priority", select "Quantity priority". Actual consumption is deducted by official-forward usage.

    <Warning>
      The Sora Official API Forwarding plan does not support the default group, legacy route groups, or pay-per-call tokens. Do not select the default group, the legacy group used by `gpt-image-2-vip`, or other legacy route groups.
    </Warning>
  </Step>

  <Step title="Call API to Generate Video">
    Follow the complete examples below to call the API.
  </Step>
</Steps>

## API Reference

### Basic Information

| Configuration      | Value                                |
| ------------------ | ------------------------------------ |
| **Base URL**       | `https://api2.laozhang.ai`           |
| **Authentication** | `Authorization: Bearer YOUR_API_KEY` |
| **Request Format** | `multipart/form-data`                |

### API Endpoints

| Endpoint                  | Method | Description                  |
| ------------------------- | ------ | ---------------------------- |
| `/v1/videos`              | POST   | Create video generation task |
| `/v1/videos/{id}`         | GET    | Query task status            |
| `/v1/videos/{id}/content` | GET    | Download generated video     |

### Request Parameters

| Parameter         | Type   | Required | Description                                      |
| ----------------- | ------ | -------- | ------------------------------------------------ |
| `model`           | string | Yes      | Model name: `sora-2` or `sora-2-pro`             |
| `prompt`          | string | Yes      | Video description text                           |
| `size`            | string | No       | Resolution, e.g. `1280x720` (default `720x1280`) |
| `seconds`         | string | No       | Video duration: `4`, `8`, or `12` (default `4`)  |
| `input_reference` | file   | No       | Reference image file (for image-to-video)        |

### Supported Resolutions (size parameter)

**sora-2:**

* `720x1280` (Portrait, default)
* `1280x720` (Landscape)

**sora-2-pro:**

* `720x1280` (Portrait)
* `1280x720` (Landscape)
* `1024x1792` (Portrait HD)
* `1792x1024` (Landscape HD)

## Complete Examples

### Text-to-Video (cURL)

**Step 1: Create Video Generation Task**

```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"
```

**Response Example:**

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

### Image-to-Video (cURL)

<Info>
  **Image-to-Video** allows you to provide a reference image as the first frame of the video. The AI will generate a dynamic video based on this image.
</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>
  **Image Requirements**

  * Image resolution must match the `size` parameter (e.g., if size=1280x720, image must be 1280×720 pixels)
  * Supported formats: JPEG, PNG, WebP
  * **Images containing real human faces are not supported** (will be rejected by content moderation)
</Warning>

**Step 2: Poll Task Status**

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

**Response Example (In Progress):**

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

**Response Example (Completed):**

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

**Step 3: Download Video**

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

### Python Example

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

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

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

# Text-to-Video
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()

# Image-to-Video
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()

# Poll task status
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: {status}, Progress: {progress}%")

        if status == "completed":
            return data
        elif status == "failed":
            raise Exception(f"Video generation failed: {data.get('error')}")

        time.sleep(interval)

    raise TimeoutError("Video generation timeout")

# Download video
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"Video saved to: {output_path}")

# Complete workflow
if __name__ == "__main__":
    # Text-to-Video
    job = create_video(
        prompt="A golden retriever playing fetch on a sunny beach",
        model="sora-2",
        seconds="8",
        size="1280x720"
    )
    print(f"Task created: {job['id']}")

    # Wait for completion
    result = poll_status(job["id"])
    print("Video generation completed!")

    # Download video
    download_video(job["id"], "my_video.mp4")

    # Image-to-Video example
    # job2 = create_video_from_image(
    #     prompt="The scene comes alive with gentle movement",
    #     image_path="reference.jpg",
    #     model="sora-2",
    #     seconds="4",
    #     size="1280x720"
    # )
```

### Task Status Reference

| Status        | Description                             |
| ------------- | --------------------------------------- |
| `queued`      | Task queued, waiting to be processed    |
| `in_progress` | Video is being generated                |
| `completed`   | Generation complete, ready for download |
| `failed`      | Generation failed                       |

<Tip>
  **Polling Recommendation**

  Video generation typically takes 2-5 minutes. We recommend polling status every 15-20 seconds to avoid excessive requests.
</Tip>

## Developer Documentation

The Official API Forwarding plan is fully compatible with OpenAI's official API format. For more parameters and advanced usage, please refer to:

<CardGroup cols={2}>
  <Card title="OpenAI Sora Official Guide" icon="book-open" href="https://platform.openai.com/docs/guides/video-generation">
    Complete video generation guide
  </Card>

  <Card title="OpenAI Videos API" icon="code" href="https://platform.openai.com/docs/api-reference/videos">
    API reference documentation
  </Card>

  <Card title="Sora 2 Model Docs" icon="cpu" href="https://platform.openai.com/docs/models/sora-2">
    sora-2 model details
  </Card>

  <Card title="Sora 2 Pro Model Docs" icon="sparkles" href="https://platform.openai.com/docs/models/sora-2-pro">
    sora-2-pro model details
  </Card>
</CardGroup>

## Important Notes

<Warning>
  **Key Limitations**

  1. **Async only**: Official API Forwarding does not support sync API, all requests are asynchronous
  2. **Usage-based billing only**: Must select "Pay-as-you-go" billing mode; pay-per-call tokens are not supported
  3. **Only two official-compatible groups are supported**: Select `Sora2Official` or `GPTImage2 Enterprise` when creating tokens
  4. **Image limitation**: Image-to-video does not support images containing real human faces
</Warning>

## FAQ

<AccordionGroup>
  <Accordion title="What's the difference between Official API Forwarding and legacy route?">
    Official API Forwarding directly calls OpenAI's official API through transparent forwarding. The legacy route was historical and is no longer the current Sora2 video integration route.
  </Accordion>

  <Accordion title="Why doesn't Official API Forwarding support sync API?">
    OpenAI's official Sora API itself only provides async calling method, so Official API Forwarding also only supports async calls.
  </Accordion>

  <Accordion title="Why are duration options different?">
    Official API Forwarding supports OpenAI's official 4/8/12 second duration options; legacy route supports the official website interface's 10/15 second durations.
  </Accordion>

  <Accordion title="What are the requirements for image-to-video?">
    Image resolution must match the target video's size parameter. For example, if size=1280x720, the image must be 1280×720 pixels. Supported formats: JPEG, PNG, WebP. Images containing real human faces are not supported.
  </Accordion>
</AccordionGroup>