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

# Sora Video Generation — Create Task API Reference Guide

> POST /v1/sora/videos — Generate 4, 8, or 12-second videos with OpenAI Sora. Set model, aspect ratio, duration, and optionally attach a reference image.

Use this endpoint to submit a new video generation task with OpenAI's Sora model. You supply a prompt, choose your model variant, set the duration and aspect ratio, and optionally attach a reference image to guide the visual style. The API responds immediately with a task `id` — you then poll the [Query Video Task](/api-reference/video/sora-query) endpoint until the video is ready.

<Note>
  Video generation is **asynchronous**. The create endpoint returns a task `id` with `status: "queued"`. Use the [Query Video Task](/api-reference/video/sora-query) endpoint to check progress and retrieve the final `video_url`.
</Note>

## Base URL & Endpoint

```
Base URL:  https://zcbservice.aizfw.cn/kyyReactApiServer
Endpoint:  POST /v1/sora/videos
Full URL:  https://zcbservice.aizfw.cn/kyyReactApiServer/v1/sora/videos
```

All requests must include your API key as a Bearer token:

```
Authorization: Bearer YOUR_API_KEY
```

## Supported Models

| Model             | Supported Durations | Notes                     |
| ----------------- | ------------------- | ------------------------- |
| `openAiSora2Plus` | 4 s · 8 s · 12 s    | Enhanced version          |
| `openAiSora2Pro`  | 4 s · 8 s · 12 s    | Higher-quality generation |

## Request Parameters

<ParamField body="model" type="string" required>
  The Sora model to use. Accepted values:

  * `openAiSora2Plus` — enhanced model, supports 4, 8, 12-second videos
  * `openAiSora2Pro` — higher-quality model, supports 4, 8, 12-second videos
</ParamField>

<ParamField body="prompt" type="string" required>
  A text description of the video you want to generate. Be specific about the scene, style, motion, and lighting.

  Example: `"A cat dancing in the rain, cinematic style"`
</ParamField>

<ParamField body="size" type="string">
  Video resolution. Use this **or** `aspect_ratio` — not both.

  * `720x1280` — portrait (default)
  * `1280x720` — landscape

  Only these two resolutions are supported. The image orientation of any reference image must match the chosen size.
</ParamField>

<ParamField body="aspect_ratio" type="string">
  Video aspect ratio. Use this **or** `size` — not both.

  * `16:9` — landscape
  * `9:16` — portrait
</ParamField>

<ParamField body="duration" type="integer">
  Video duration in seconds. Accepted values: `4`, `8`, `12`.

  Use this **or** `seconds` — not both.
</ParamField>

<ParamField body="seconds" type="integer">
  Video duration in seconds. Accepted values: `4`, `8`, `12`.

  Use this **or** `duration` — not both.
</ParamField>

<ParamField body="input_reference" type="array">
  An array of reference image URLs to guide video style and content. Maximum **1 image**.

  Use this **or** `image_urls` — not both.

  **Constraints:**

  * Do not use real portrait photographs — these will likely cause generation failures.
  * Image dimensions must match the chosen ratio: `1280×720` for 16:9, or `720×1280` for 9:16.
</ParamField>

<ParamField body="image_urls" type="array">
  An array of reference image URLs to guide video style and content. Maximum **1 image**.

  Use this **or** `input_reference` — not both.

  **Constraints:**

  * Do not use real portrait photographs — these will likely cause generation failures.
  * Image dimensions must match the chosen ratio: `1280×720` for 16:9, or `720×1280` for 9:16.
</ParamField>

## Response Fields

<ResponseField name="id" type="string">
  Unique identifier for the video generation task. Save this value — you will use it to poll the [Query Video Task](/api-reference/video/sora-query) endpoint.
</ResponseField>

<ResponseField name="object" type="string">
  Object type. Always `"video.generation"`.
</ResponseField>

<ResponseField name="created" type="integer">
  Unix timestamp (seconds) of when the task was created.
</ResponseField>

<ResponseField name="model" type="string">
  The model name you specified in the request.
</ResponseField>

<ResponseField name="status" type="string">
  Initial task status. On successful creation this is always `"queued"`.
</ResponseField>

<ResponseField name="error" type="string">
  Error message. Only present when `status` is `"failed"`.
</ResponseField>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://zcbservice.aizfw.cn/kyyReactApiServer/v1/sora/videos \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "openAiSora2Plus",
      "prompt": "A cat dancing in the rain, cinematic style",
      "aspect_ratio": "16:9",
      "seconds": 8,
      "input_reference": [
        "https://example.com/reference1.jpg"
      ]
    }'
  ```

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

  url = "https://zcbservice.aizfw.cn/kyyReactApiServer/v1/sora/videos"

  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
  }

  payload = {
      "model": "openAiSora2Plus",
      "prompt": "A cat dancing in the rain, cinematic style",
      "aspect_ratio": "16:9",
      "seconds": 8,
      "input_reference": [
          "https://example.com/reference1.jpg"
      ],
  }

  response = requests.post(url, headers=headers, json=payload)
  data = response.json()

  task_id = data["id"]
  print(f"Task created: {task_id} — status: {data['status']}")
  ```
</CodeGroup>

**Example success response:**

```json theme={null}
{
  "id": "sora_abc123def456",
  "object": "video.generation",
  "created": 1761635478,
  "model": "openAiSora2Plus",
  "status": "queued"
}
```

## Parameter Mutual Exclusivity

| Group           | Choose one                            |
| --------------- | ------------------------------------- |
| Resolution      | `size` **or** `aspect_ratio`          |
| Duration        | `duration` **or** `seconds`           |
| Reference image | `input_reference` **or** `image_urls` |

## Tips

<Tip>
  **Write better prompts** — include a specific scene description, style keywords (e.g. `"cinematic"`, `"artistic"`, `"realistic"`), motion descriptions, and lighting preferences for best results.
</Tip>

<Warning>
  **Avoid real portrait photos** as reference images. The Sora model does not support realistic human faces and such requests will almost always fail. Use stylised or illustrated imagery instead.
</Warning>

<Tip>
  After creating a task, poll the [Query Video Task](/api-reference/video/sora-query) endpoint every **30–60 seconds**. A typical 8-second video takes 2–5 minutes to generate.
</Tip>