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

# Videos API: Create Video Generation Task (Standard and Fast)

> POST /v1/videos/videos — Generate 4–15s 720p videos with the Videos or Videos Fast model. Supports text, first/last frame, and multi-modal reference.

Submit an asynchronous video generation task using the Videos model series. The endpoint returns a task `id` immediately — you then poll the [Query Video Task](/api-reference/video/videos-query) endpoint until the task reaches `completed` or `failed`. The Videos series supports pure text-to-video, first/last frame guidance, and a powerful multi-modal reference mode combining image and video inputs.

## Base URL

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

## Endpoint

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

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Models

| Model         | Billing  | Duration | Resolution | Best For                  |
| ------------- | -------- | -------- | ---------- | ------------------------- |
| `videos`      | Per call | 4–15s    | 720p       | Standard quality output   |
| `videos_fast` | Per call | 4–15s    | 720p       | Speed-sensitive workflows |

<Tip>
  Use **`videos`** for the highest-quality output. Use **`videos_fast`** when turnaround speed matters more than maximum quality.
</Tip>

## Request Parameters

<ParamField body="model" type="string" required>
  The model to use for generation.

  Supported values:

  * `videos` — standard model
  * `videos_fast` — faster generation
</ParamField>

<ParamField body="prompt" type="string" required>
  Text description of the video content. Maximum **1500 characters**.

  Include subject, action, camera movement, and visual style. Avoid content that violates platform policies (e.g., restricted, infringing, or sensitive subject matter).

  **Example:** `"A cute kitten playing on a sunlit meadow, cinematic lens"`
</ParamField>

<ParamField body="duration" type="integer" required>
  Output video duration in seconds. Required.

  * Supported range: `4`–`15` seconds
</ParamField>

<ParamField body="ratio" type="string">
  Output aspect ratio. Defaults to `16:9`.

  | Value  | Description         |
  | ------ | ------------------- |
  | `16:9` | Landscape (default) |
  | `9:16` | Portrait            |
  | `1:1`  | Square              |
</ParamField>

<ParamField body="resolution" type="string">
  Output resolution. Currently only `720p` is supported.

  Default: `720p`
</ParamField>

### First / Last Frame Mode

Use these fields to guide the video's starting and ending frames. Both fields are required together.

<ParamField body="first_image" type="string">
  URL of the first-frame image.

  * Required to be used with `last_image`
  * Cannot be combined with `referenceImages` or `referenceVideos`
</ParamField>

<ParamField body="last_image" type="string">
  URL of the last-frame image.

  * Required to be used with `first_image`
  * Cannot be combined with `referenceImages` or `referenceVideos`
</ParamField>

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

### Reference Media Mode

Use these fields to provide reference images and/or videos that guide the generated output. They can be used individually or combined.

<ParamField body="referenceImages" type="array">
  Array of reference image URLs.

  * Maximum **4** images
  * Each image must be under **20 MB**
  * Can be combined with `referenceVideos` for mixed-media reference
  * Cannot be used with `first_image` or `last_image`
</ParamField>

<ParamField body="referenceVideos" type="array">
  Array of reference video URLs.

  * Maximum **3** videos
  * Total combined duration must not exceed **15 seconds**
  * Total combined size must not exceed **200 MB**
  * Each video must be between **720px and 2160px** in resolution
  * Can be combined with `referenceImages`
  * Cannot be used with `first_image` or `last_image`
</ParamField>

### Legacy Compatibility

<Note>
  The legacy fields `image` (alias for `first_image`) and `lastFrameImage` (alias for `last_image`) are still supported for backwards compatibility.

  If you pass both a legacy field and its new counterpart with conflicting values, the API will return a parameter conflict error. When both are present with the same value, `first_image`/`last_image` take precedence.
</Note>

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

## Generation Modes

| Mode             | Fields Required                                                     | Notes                               |
| ---------------- | ------------------------------------------------------------------- | ----------------------------------- |
| Text-to-video    | `model`, `prompt`, `duration`                                       | Optional: `ratio`, `resolution`     |
| First/last frame | `model`, `prompt`, `duration`, `first_image`, `last_image`          | Both frame fields required together |
| Image reference  | `model`, `prompt`, `duration`, `referenceImages`                    | Up to 4 images, each \< 20 MB       |
| Video reference  | `model`, `prompt`, `duration`, `referenceVideos`                    | Up to 3 videos, ≤15s total          |
| Image + video    | `model`, `prompt`, `duration`, `referenceImages`, `referenceVideos` | Combined constraints apply          |

## Code Examples

<CodeGroup>
  ```bash cURL (Text-to-Video) theme={null}
  curl --request POST \
    --url https://zcbservice.aizfw.cn/kyyReactApiServer/v1/videos/videos \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "videos",
      "prompt": "A cute kitten playing on a sunlit meadow, cinematic lens",
      "duration": 5,
      "ratio": "16:9",
      "resolution": "720p"
    }'
  ```

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

  ```bash cURL (Image + Video Reference) theme={null}
  curl --request POST \
    --url https://zcbservice.aizfw.cn/kyyReactApiServer/v1/videos/videos \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "videos",
      "prompt": "The character runs through the forest as seen in the reference",
      "duration": 8,
      "ratio": "16:9",
      "referenceImages": [
        "https://example.com/character.jpg"
      ],
      "referenceVideos": [
        "https://example.com/motion-reference.mp4"
      ]
    }'
  ```

  ```python Python (Text-to-Video) theme={null}
  import requests

  response = requests.post(
      "https://zcbservice.aizfw.cn/kyyReactApiServer/v1/videos/videos",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      json={
          "model": "videos",
          "prompt": "A cute kitten playing on a sunlit meadow, cinematic lens",
          "duration": 5,
          "ratio": "16:9",
          "resolution": "720p",
      },
  )

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

### Example Response

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

## Next Steps

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