# PixVerse V6 Video API Reference

Create PixVerse V6 text, image, transition, reference, and extension tasks through Imya.

> Developer Preview: verify one real billed task and terminal credit settlement in the target deployment before treating this contract as production-ready.

## Authentication

```http
POST https://imya.ai/v1/videos/generations
Authorization: Bearer YOUR_IMYA_API_KEY
Content-Type: application/json
Idempotency-Key: your-unique-request-id
```

Every logical generation needs a unique idempotency key. Reusing the same key with the same request returns the original task without a second charge.

## Common fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| model | string | Yes | Use `pixverse-v6`. |
| mode | string | Yes | `text-to-video`, `image-to-video`, `transition`, `reference-to-video`, or `extend`. |
| prompt | string | Yes | 3-5,000 characters. |
| duration | integer | No | 1-15 seconds; default 5. |
| quality | string | No | `360p`, `540p`, `720p`, or `1080p`; default `720p`. |
| aspect_ratio | string | Conditional | Text and reference modes only: `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `2:3`, `3:2`, or `21:9`. |
| generate_audio | boolean | No | Native audio; default false. |
| generate_multi_clip | boolean | No | Text and image modes only; default false. |
| seed | integer | No | 0-2147483647. |

All media URLs must be public HTTPS URLs.

## Text to video

```json
{
  "model": "pixverse-v6",
  "mode": "text-to-video",
  "prompt": "A paper crane unfolds and flies into sunrise",
  "duration": 5,
  "quality": "720p",
  "aspect_ratio": "16:9",
  "generate_audio": true,
  "generate_multi_clip": false
}
```

## Image to video

`image_urls` requires one or two JPG, PNG, or WebP images.

```json
{
  "model": "pixverse-v6",
  "mode": "image-to-video",
  "prompt": "The subject turns as the camera arcs slowly left",
  "image_urls": ["https://cdn.example.com/start.png"],
  "duration": 5,
  "quality": "720p",
  "generate_audio": true
}
```

## First and last frame transition

```json
{
  "model": "pixverse-v6",
  "mode": "transition",
  "prompt": "Connect the scenes with one continuous paper-fold transformation",
  "first_frame_image_url": "https://cdn.example.com/first.png",
  "last_frame_image_url": "https://cdn.example.com/last.png",
  "duration": 6,
  "quality": "1080p"
}
```

## Reference to video

`image_references` accepts 1-7 items. Optional `ref_name` values must be unique and may be used as `@name` in the prompt.

```json
{
  "model": "pixverse-v6",
  "mode": "reference-to-video",
  "prompt": "Keep @hero consistent while the camera enters @studio",
  "image_references": [
    {
      "image_url": "https://cdn.example.com/hero.png",
      "type": "subject",
      "ref_name": "hero"
    },
    {
      "image_url": "https://cdn.example.com/studio.png",
      "type": "background",
      "ref_name": "studio"
    }
  ],
  "duration": 5,
  "quality": "720p",
  "aspect_ratio": "9:16"
}
```

## Extend video

Send exactly one of `video_url` or `parent_task_id`. A parent task ID must be the public Imya ID of a completed PixVerse task owned by the same account. Provider task IDs are never accepted.

```json
{
  "model": "pixverse-v6",
  "mode": "extend",
  "prompt": "Continue the forward camera move into the bright atrium",
  "video_url": "https://cdn.example.com/source.mp4",
  "duration": 5,
  "quality": "720p"
}
```

## Task response and polling

New tasks return HTTP 202 with an Imya task ID and the exact account-specific credit reservation:

```json
{
  "id": "task_0123456789abcdef0123456789abcdef",
  "status": "processing",
  "model": "pixverse-v6",
  "credits_reserved": 125
}
```

Poll at least five seconds apart:

```http
GET https://imya.ai/v1/tasks/task_0123456789abcdef0123456789abcdef
Authorization: Bearer YOUR_IMYA_API_KEY
```

The task reports `pending`, `processing`, `succeeded`, or `failed`. Successful tasks include video URLs in `data`. Eligible failed reservations are refunded exactly once; `refund_pending` means settlement has not finished.

Do not cache credit prices. Duration, quality, native audio, reference mode, and the API-key owner's plan all affect `credits_reserved`.