> ## 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.

# StarVideos O3: Create Video Task (Text, Image, Frame Modes)

> POST /v1/starvideos/videos — Generate 3–15s videos with starvideos_o3. Supports text, multi-image reference, first/last frame, and video reference.

Submit an asynchronous video generation task using the `starvideos_o3` model. The endpoint returns a task `id` immediately — you then poll the [Query Video Task](/api-reference/video/starvideos-query) endpoint until the task completes. StarVideos O3 supports a rich set of generation modes: pure text-to-video, single or multi-image reference, first/last frame guidance, video reference, and combined image + video reference.

## Base URL

```
https://zcbservice.aizfw.cn/kyyReactApiServer
```

## Endpoint

```
POST /v1/starvideos/videos
```

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Model

This endpoint supports a single model:

| Model           | Duration           | Aspect Ratios         | Notes                                                    |
| --------------- | ------------------ | --------------------- | -------------------------------------------------------- |
| `starvideos_o3` | 3–15s (default 3s) | `9:16`, `1:1`, `16:9` | Multi-mode: text, image ref, first/last frame, video ref |

## Request Parameters

<ParamField body="model" type="string" required>
  Model name. Must be `starvideos_o3`.
</ParamField>

<ParamField body="prompt" type="string" required>
  Text description of the video content, including subject, action, camera movement, and visual style.

  **Example:** `"Cyberpunk cityscape at night, camera slowly pushing forward"`
</ParamField>

<ParamField body="duration" type="integer">
  Output video duration in seconds. Applies to text-to-video, image reference, and first/last frame modes.

  * Default: `3`
  * Supported range: `3`–`15` seconds

  <Note>
    When using `referenceVideos` (video reference, image + video, or multi-image + video modes), the output duration and aspect ratio are determined by the reference video — this field is ignored.
  </Note>
</ParamField>

<ParamField body="ratio" type="string">
  Output aspect ratio. Applies to text-to-video, image reference, and first/last frame modes.

  * Default: `9:16`
  * Supported values: `9:16`, `1:1`, `16:9`

  <Note>
    When using `referenceVideos`, the aspect ratio follows the reference video's dimensions — this field is ignored.
  </Note>
</ParamField>

### Image Reference Parameters

<ParamField body="referenceImages" type="array">
  Array of image reference URLs. Used in image reference mode and combined image + video reference mode.

  Constraints:

  * **Image reference only (no video):** up to **7** images
  * **Combined with `referenceVideos`:** up to **4** images

  **Example:** `["https://example.com/ref1.jpg", "https://example.com/ref2.jpg"]`
</ParamField>

### First / Last Frame Parameters

<ParamField body="first_image" type="string">
  URL of the first-frame image. For first/last frame mode — must be used together with `last_image`.

  Cannot be combined with `referenceImages` or `referenceVideos`.
</ParamField>

<ParamField body="last_image" type="string">
  URL of the last-frame image. For first/last frame mode — must be used together with `first_image`.

  Cannot be combined with `referenceImages` or `referenceVideos`.
</ParamField>

### Video Reference Parameters

<ParamField body="referenceVideos" type="array">
  Array of reference video URLs. Enables video reference mode. Maximum **1** video.

  * Reference video duration must be **3–10 seconds**
  * When provided, output duration and ratio follow the reference video
  * Can be combined with `referenceImages` (up to 4 images)

  **Example:** `["https://example.com/reference.mp4"]`
</ParamField>

<Warning>
  `first_image` / `last_image` are **mutually exclusive** with `referenceImages` and `referenceVideos`. You cannot mix first/last frame mode with reference media mode in the same request.
</Warning>

## Generation Modes

StarVideos O3 supports the following mutually exclusive modes:

| Mode             | Required Fields                                                   | Optional Fields             |
| ---------------- | ----------------------------------------------------------------- | --------------------------- |
| Text-to-video    | `model`, `prompt`                                                 | `duration`, `ratio`         |
| Image reference  | `model`, `prompt`, `referenceImages` (1–7)                        | `duration`, `ratio`         |
| First/last frame | `model`, `prompt`, `first_image`, `last_image`                    | `duration`, `ratio`         |
| Video reference  | `model`, `prompt`, `referenceVideos` (1 video)                    | — duration/ratio from video |
| Image + Video    | `model`, `prompt`, `referenceImages` (1–4), `referenceVideos` (1) | — duration/ratio from video |

## Response Fields

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

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

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

<ResponseField name="model" type="string">
  The model name used for this task. Always `"starvideos_o3"`.
</ResponseField>

<ResponseField name="status" type="string">
  Task status at creation. Always `"queued"` on successful submission.

  Lifecycle values:

  * `queued` — task accepted and waiting in queue
  * `processing` — model is actively generating
  * `completed` — generation finished; `video_url` is available
  * `failed` — generation failed; see `error`
</ResponseField>

<ResponseField name="error" type="string">
  Error message. `null` on successful submission.
</ResponseField>

## Code Examples

<CodeGroup>
  ```bash cURL (Text-to-Video) theme={null}
  curl --request POST \
    --url https://zcbservice.aizfw.cn/kyyReactApiServer/v1/starvideos/videos \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "starvideos_o3",
      "prompt": "Cyberpunk cityscape at night, camera slowly pushing forward",
      "duration": 5,
      "ratio": "16:9"
    }'
  ```

  ```bash cURL (Image Reference) theme={null}
  curl --request POST \
    --url https://zcbservice.aizfw.cn/kyyReactApiServer/v1/starvideos/videos \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "starvideos_o3",
      "prompt": "The character walks through the neon-lit streets at night",
      "duration": 5,
      "ratio": "16:9",
      "referenceImages": [
        "https://example.com/character.jpg",
        "https://example.com/scene.jpg"
      ]
    }'
  ```

  ```bash cURL (First/Last Frame) theme={null}
  curl --request POST \
    --url https://zcbservice.aizfw.cn/kyyReactApiServer/v1/starvideos/videos \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "starvideos_o3",
      "prompt": "Smooth cinematic transition between the two scenes",
      "duration": 5,
      "ratio": "16:9",
      "first_image": "https://example.com/scene-start.jpg",
      "last_image": "https://example.com/scene-end.jpg"
    }'
  ```

  ```python Python (Image Reference) theme={null}
  import requests

  response = requests.post(
      "https://zcbservice.aizfw.cn/kyyReactApiServer/v1/starvideos/videos",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      json={
          "model": "starvideos_o3",
          "prompt": "The character walks through the neon-lit streets at night",
          "duration": 5,
          "ratio": "16:9",
          "referenceImages": [
              "https://example.com/character.jpg",
          ],
      },
  )

  task = response.json()
  print("Task ID:", task["id"])
  print("Status:", task["status"])
  ```
</CodeGroup>

### Example Response

```json theme={null}
{
  "id": "video_starvideos_o3_1234567890",
  "object": "video",
  "created": 1774836724,
  "model": "starvideos_o3",
  "status": "queued",
  "error": null
}
```

## Next Steps

After receiving the task `id`, poll the [Query Video Task](/api-reference/video/starvideos-query) endpoint to check status and retrieve `video_url` when generation completes.