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

# Pixverse v6 Video Generation

>  - Pixverse v6 unified video generation model
- Supports text-to-video, image-to-video, first/last frame transition, multi-reference fusion, and video extension
- Supports 360p/540p/720p/1080p resolutions with 1-15 seconds duration
- Asynchronous task API; query the result by task ID after submission 

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://gccai.heqingsong.uk/v1/videos/generations \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "pixverse-v6",
      "prompt": "A cinematic shot of a corgi running through a sunflower field at golden hour",
      "size": "16:9",
      "resolution": "540p",
      "duration": 5
    }'
  ```

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

  url = "https://gccai.heqingsong.uk/v1/videos/generations"

  payload = {
      "model": "pixverse-v6",
      "prompt": "A cinematic shot of a corgi running through a sunflower field at golden hour",
      "size": "16:9",
      "resolution": "540p",
      "duration": 5
  }

  headers = {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
  }

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

  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const url = "https://gccai.heqingsong.uk/v1/videos/generations";

  const payload = {
    model: "pixverse-v6",
    prompt: "A cinematic shot of a corgi running through a sunflower field at golden hour",
    size: "16:9",
    resolution: "540p",
    duration: 5
  };

  const headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  };

  fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(payload)
  })
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error("Error:", error));
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "code": 200,
    "data": [
      {
        "status": "submitted",
        "task_id": "task_01JWXXXXXXXXXXXX"
      }
    ]
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "type": "invalid_request_error",
      "message": "invalid duration 20, allowed range: 1-15 seconds"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": 401,
      "message": "Authentication failed, please check your API key",
      "type": "authentication_error"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": 403,
      "message": "insufficient quota: balance=0, required=0.25",
      "type": "quota_not_enough"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": 429,
      "message": "Too many requests, please try again later",
      "type": "rate_limit_error"
    }
  }
  ```
</ResponseExample>

## Authentication

<ParamField header="Authorization" type="string" required>
  All endpoints require authentication using a Bearer Token.

  Get an API Key:

  Visit the [API Key management page](https://gccai.heqingsong.uk/keys) to obtain your API Key.

  Add the following header in your request:

  ```
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## Request Parameters

<ParamField body="model" type="string" required>
  Video generation model name. Fixed to `pixverse-v6`.
</ParamField>

<ParamField body="prompt" type="string" required>
  Video content description, up to 5000 characters. Required for all modes.
</ParamField>

<ParamField body="resolution" type="string" default="540p">
  Video resolution tier; directly affects pricing.

  * `360p`: SD
  * `540p`: Standard (default)
  * `720p`: HD
  * `1080p`: Full HD

  <Warning>
    Other resolution values will return a parameter error.
  </Warning>
</ParamField>

<ParamField body="duration" type="integer" default="5">
  Video duration in seconds, range `1-15`.

  <Warning>
    First/last frame transition mode only supports `5` or `8` seconds.
  </Warning>
</ParamField>

<ParamField body="size" type="string" default="16:9">
  Video aspect ratio. Only effective in text-to-video and multi-reference fusion modes.

  * `16:9`: Landscape widescreen (default)
  * `4:3`: Landscape 4:3
  * `1:1`: Square
  * `3:4`: Portrait 3:4
  * `9:16`: Portrait vertical
  * `2:3`: Portrait 2:3
  * `3:2`: Landscape 3:2
  * `21:9`: Cinematic widescreen
</ParamField>

<ParamField body="seed" type="integer" default="0">
  Random seed, range `0-2147483647`. Same prompt and seed can reproduce similar results.
</ParamField>

<ParamField body="negative_prompt" type="string">
  Negative prompt used to exclude unwanted content, up to 2048 characters.
</ParamField>

<ParamField body="audio" type="boolean" default="false">
  Whether to generate an audio track.

  * `true`: Generate audio (increases pricing)
  * `false`: No audio (default)
</ParamField>

<ParamField body="watermark" type="boolean" default="false">
  Whether to add a watermark in the bottom-right corner of the video.

  * `true`: Add watermark
  * `false`: No watermark (default)
</ParamField>

<ParamField body="motion_mode" type="string">
  Motion mode.

  * `normal`: Standard mode (`pixverse-v6` only supports this value)

  <Warning>
    `fast` only applies to legacy models and will be rejected by the upstream when used with `pixverse-v6`.
  </Warning>
</ParamField>

<ParamField body="generate_multi_clip_switch" type="boolean" default="false">
  Whether to generate a multi-clip continuous video. Only supported in text-to-video and image-to-video modes.

  * `true`: Generate multi-clip continuous video
  * `false`: Single clip (default)
</ParamField>

<ParamField body="image_urls" type="array<url>">
  Input image URL array for image-to-video; only the first image is used.

  Images must be publicly accessible HTTP/HTTPS URLs.
</ParamField>

<ParamField body="first_frame_image" type="url">
  First frame image URL for transition mode. Must be provided together with `last_frame_image`.
</ParamField>

<ParamField body="last_frame_image" type="url">
  Last frame image URL for transition mode. Must be provided together with `first_frame_image`.
</ParamField>

<ParamField body="img_references" type="array<url>">
  Reference image URL array for multi-reference fusion mode; supports 1-7 images.

  Providing this field triggers multi-reference fusion mode.
</ParamField>

<ParamField body="extend_from_task_id" type="string">
  Source task ID for video extension. Providing this field triggers video extension mode.

  The source task must belong to the current user, use model `pixverse-v6`, and have status `completed`.
</ParamField>

## Generation Modes

The adapter automatically dispatches to the corresponding generation mode based on request fields. Matching is done in priority order; the first match wins.

| Mode                        | Trigger                                                  | Description                                        |
| --------------------------- | -------------------------------------------------------- | -------------------------------------------------- |
| Text-to-video               | No image or extension fields                             | Generate video based on `prompt`                   |
| Image-to-video              | `image_urls` with one image                              | Use the first image as input                       |
| First/last frame transition | Both `first_frame_image` and `last_frame_image` provided | Generate a smooth transition between two frames    |
| Multi-reference fusion      | `img_references` array provided                          | Fuse 1-7 reference images into a video             |
| Video extension             | `extend_from_task_id` provided                           | Continue generation from a completed Pixverse task |

<Warning>
  All image inputs only accept publicly accessible HTTP/HTTPS URLs. base64 and Data URI are not supported. If you only have local images, upload them to object storage first and pass the URL.
</Warning>

## Parameter Rules

| Constraint             | Description                                                                                    |
| ---------------------- | ---------------------------------------------------------------------------------------------- |
| Duration               | `1 ≤ duration ≤ 15` seconds; transition mode only supports `5` or `8` seconds                  |
| Resolution             | Only `360p`, `540p`, `720p`, `1080p` are supported                                             |
| Aspect ratio           | `size` is only effective in text-to-video and multi-reference fusion modes                     |
| Prompt length          | `prompt` up to 5000 chars, `negative_prompt` up to 2048 chars                                  |
| Image-to-video         | `image_urls` only uses the first image                                                         |
| Transition             | `first_frame_image` and `last_frame_image` must be provided together                           |
| Motion mode            | `pixverse-v6` only supports `normal`                                                           |
| Multi-reference fusion | `img_references` supports 1-7 images                                                           |
| Video extension        | `extend_from_task_id` must point to a `completed` `pixverse-v6` task owned by the current user |

## Response

<ResponseField name="code" type="integer">
  Response status code. `200` on success.
</ResponseField>

<ResponseField name="data" type="array">
  Returned task array.

  <Expandable title="Array element">
    <ResponseField name="status" type="string">
      Initial task status. `submitted` upon successful submission.
    </ResponseField>

    <ResponseField name="task_id" type="string">
      Unique task identifier used for querying status and results.
    </ResponseField>
  </Expandable>
</ResponseField>

## Querying Task Results

Video generation is an asynchronous task. After submission, a `task_id` is returned. Use the [Get Task Status](/en/api-reference/tasks/status) endpoint to query progress and results.

```bash cURL theme={null}
curl --request GET \
  --url https://gccai.heqingsong.uk/v1/tasks/task_01JWXXXXXXXXXXXX \
  --header 'Authorization: Bearer <token>'
```

It is recommended to poll every 5 seconds until the status becomes `completed` or `failed`.

### Successful Result Example

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KSPX48B8V1M6C2ZN0D0T4BKB",
    "status": "completed",
    "progress": 100,
    "cost": 0.2,
    "credits_cost": 2,
    "created": 1779958948,
    "completed": 1779958999,
    "estimated_time": 100,
    "actual_time": 51,
    "result": {
      "videos": [
        {
          "url": ["https://upload.gccai.ai/f/video/xxxx.mp4"],
          "expires_at": 1780045399
        }
      ]
    }
  }
}
```

The video URL is at `data.result.videos[0].url[0]`. The `url` field is itself an array. Video links typically expire after 24 hours; download or transfer them in time.

### Failed Result Example

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KSPX48B8V1M6C2ZN0D0T4BKB",
    "status": "failed",
    "progress": 100,
    "cost": 0,
    "credits_cost": 0,
    "created": 1779958948,
    "completed": 1779958960,
    "error": {
      "code": "task_failed",
      "message": "pixverse error 400063: moderation failed",
      "type": "task_failed"
    }
  }
}
```

On failure, `cost` is typically `0`. Read the error reason from `data.error.message`.

## Use Cases

### Case 1: Text-to-video

```json theme={null}
{
  "model": "pixverse-v6",
  "prompt": "A neon-lit alley in Tokyo at night, light rain, anamorphic lens flare",
  "size": "21:9",
  "resolution": "720p",
  "duration": 8,
  "seed": 42,
  "audio": true
}
```

### Case 2: Image-to-video

```json theme={null}
{
  "model": "pixverse-v6",
  "prompt": "Camera slowly zooms in, gentle wind moves the leaves",
  "image_urls": ["https://example.com/first-frame.jpg"],
  "resolution": "540p",
  "duration": 5
}
```

### Case 3: First/Last Frame Transition

```json theme={null}
{
  "model": "pixverse-v6",
  "prompt": "transform smoothly from a puppy to a cat",
  "first_frame_image": "https://example.com/puppy.jpg",
  "last_frame_image": "https://example.com/cat.jpg",
  "resolution": "540p",
  "duration": 5,
  "motion_mode": "normal"
}
```

### Case 4: Multi-Reference Fusion

```json theme={null}
{
  "model": "pixverse-v6",
  "prompt": "A girl wearing the outfit from image 2, holding the cat from image 3",
  "img_references": [
    "https://example.com/character.jpg",
    "https://example.com/outfit.jpg",
    "https://example.com/cat.jpg"
  ],
  "size": "9:16",
  "resolution": "720p",
  "duration": 5
}
```

### Case 5: Video Extension

```json theme={null}
{
  "model": "pixverse-v6",
  "prompt": "the character now walks into a forest",
  "extend_from_task_id": "task_01JWXXXXXXXXXXXX",
  "resolution": "540p",
  "duration": 5
}
```