# Wan 3.0

Text to video up to 30 seconds, with native audio.

- Model ID: `alibaba/wan3.0-video/text-to-video`
- Provider: Alibaba
- Modality: text → video
- Type: Text to Video
- Status: stable
- Delivery: async
- Max resolution: 1080p
- Output format: mp4
- Aspect ratios: adaptive, 16:9, 4:3, 1:1, 3:4, 9:16

## Authentication

Send your API key in the `X-API-Key` header.

The same key reads the org balance at `GET https://api.dev.pika.art/billing/balance`, which is free to call and confirms the request can be paid for before you submit it.

## Endpoint

```
POST https://api.dev.pika.art/v1/media/alibaba/wan3.0-video/text-to-video
```

## Reference uploads

To use a local file (image, audio, or video) as a model input, first request a presigned upload URL: `POST /v1/media/uploads` with the `X-API-Key` header and a JSON body `{ "content_type": "image/png", "size_bytes": 12345 }`, where `size_bytes` is the file's exact byte length. The response returns `upload_url` (temporary, valid for 5 minutes), `headers`, and `url` (the permanent Pika URL). PUT the file bytes to `upload_url` sending the returned `headers` verbatim — both `Content-Type` and `Content-Length` are signed, and storage returns a bare 403 if either is missing or differs. Then pass `url` into fields such as `image`, `image_url`, `end_image_url`, `image_urls`, `first_frame_image`, or `mask_image_url`.

## Generate

`POST /v1/media/alibaba/wan3.0-video/text-to-video`

```bash
curl -X POST https://api.dev.pika.art/v1/media/alibaba/wan3.0-video/text-to-video \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "WIDE 16:9 CINEMATIC LETTERBOX PANORAMA — twice as wide as tall, like a cinema screen. NOT square, NOT vertical. A single continuous 10-second shot that travels from above the water to below it.\nTHE SCENE. A rectangular tiled bathing pool fills the frame from the far left edge to the far right edge as a long horizontal band, seen slightly from above and square-on; the pool's tiled steps and shallow ledges run along the left and right edges as symmetrical leading lines, the far tiled wall closing the top third, the still water filling the whole lower half. One woman is submerged in the pool up to her chin, only her head above the waterline, dead centre in frame, dark hair slicked flat and wet against her scalp with a centre parting, water beading on her forehead and running down her temples, chin level, facing camera, deadpan, entirely still. The water is pale and milky at the surface, perfectly calm, unbroken but for the meniscus curving where it meets her jaw. The pool is lined edge to edge in matte glazed square ceramic tiles in a soft chalky RED — a dusty brick-rose red at a gentle, low-to-moderate saturation, exactly as soft as a pale sage green, chalky and powdery rather than vivid: NOT scarlet, NOT crimson, NOT a bright saturated red, NOT a strong primary. The same soft tone across the far wall, the steps and the ledges, with pale grout lines and a faint mottled variation in the glaze.\nTHE MOTION. One unbroken shot, no cuts. FIRST BEAT: she holds absolutely still at the surface, deadpan, chin level, the water flat around her. She draws one slow breath in, her chest lifting, and closes her mouth. SECOND BEAT: she lowers herself straight down and submerges — sinking smoothly, not falling, the waterline climbing over her mouth, over her nose, over her open eyes, over her hair, until the milky surface closes above her and seals flat again. The camera SINKS WITH HER, descending in one continuous move and passing THROUGH the waterline in the middle of the shot — a brief blurred smear of surface and spray across the lens as it crosses — and comes out underwater, now fully submerged with her. THIRD BEAT: underwater. Her face fills more of the frame, lit softly from above, hair lifting and drifting slowly around her head in the water, the red tiles of the pool walls visible behind her but diffused and desaturated by the water. She holds her breath, cheeks faintly full, eyes open and steady on the camera, still deadpan. Then she parts her lips and slowly BLOWS OUT A STREAM OF AIR — a rising column of silver bubbles of mixed sizes tumbling and wobbling upward past her cheeks and forehead towards the surface, catching the light, the last few small ones trailing after. She keeps looking at the camera the whole time. Below the surface the water is clear enough to see her face and the tiled walls softly — hazy and diffused, never opaque, never black, never murky.\nColour: soft but vibrant — never oversaturated, never desaturated or washed out. Build one complementary pairing: pale milky cool water and bare skin against the soft chalky red tile. Colours true; no cast, no teal-and-orange or stylised tint. Contrast controlled, low-to-moderate. Do not let brown, tan, beige, khaki, sepia or muddy earthy tones spread through the frame. Lighting: bright, high-key and luminous like an airy daylight studio or a clean overcast day — light-filled and open, never dark, never moody, never low-key. A large soft close source from above, carrying down through the water as soft shafts. Shadows filled so texture holds in skin and tile; shadows soft but PRESENT. No bare flash, no harsh sun, no sharp-edged shadows. Light neutral and true, never coloured for mood. Skin with real photographic texture — visible pores, fine hairs, freckles, natural variation in tone, never smoothed or retouched or plastic. Anatomy correct and believable, face correctly formed and symmetrical, eyes level. Film texture: shot on real photographic film, medium-format or 35mm, fine organic grain across the whole frame, gentle halation where bright highlights meet darker tone, filmic and analogue, never clinical, never digitally sharp — no HDR, no clarity, no over-sharpening. Natural restrained grade, blacks open, slightly creamy finish, highlights rolling off softly. Deadpan, entirely straight-faced, quiet dry wit. Elevated high-end fashion campaign film. No text, no lettering, no logos, no branding, no watermark.\nAudio: above water — quiet tiled-room reverb, a faint lap of water against tile, one clear intake of breath. As the camera crosses the surface, the sound drops abruptly into a muffled underwater world: a low pressure hum, everything distant and dulled. Then the soft burble and rush of exhaled bubbles rising and popping. No music, no dialogue, no narration.",
  "resolution": "1080p",
  "ratio": "adaptive",
  "duration": 5,
  "audio": true,
  "watermark": false
}'
```

### Request body

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `prompt` | string | yes | - | Text prompt (max 20000 chars). |
| `resolution` | enum | no | 1080p | Output resolution. |
| `ratio` | enum | no | adaptive | Output aspect ratio; 'adaptive' lets the model choose. |
| `duration` | enum | no | 5 | Output length in seconds (2-30), or 'auto' for smart duration. |
| `audio` | boolean | no | true | Whether to generate audio. |
| `seed` | integer | no | - | Deterministic seed. |
| `watermark` | boolean | no | false | Also return a watermarked result. |

### Accepted values

| Param | Values | Default |
| --- | --- | --- |
| `resolution` | `480p`, `720p`, `1080p` | `1080p` |
| `ratio` | `adaptive`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16` | `adaptive` |

Returns a job object, not the final output — normally with status `queued`. Store the `id` and poll until a terminal state. A rejected submit (insufficient balance, rate limit, unpriceable input) still returns the job object, with status `failed` and `error` set. An `Idempotency-Key` replay returns the existing job in its current state — including `failed`, so retry a failure with a fresh key, never the same one.

### Response

**200 OK · queued**

```json
{
  "id": "media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0",
  "status": "queued"
}
```

## Poll status

`GET /v1/media/jobs/{request_id}`

```bash
curl https://api.dev.pika.art/v1/media/jobs/{request_id} \
  -H "X-API-Key: YOUR_API_KEY"
```

Poll the job by id until it reaches a terminal state: `completed` or `failed`.

### The job object

- `id` (string): Unique identifier for the job.
- `status` (enum): One of `queued`, `running`, `completed`, `failed`.
- `output` (object): Present once the job completes.
  - `media_type` (enum): `video`.
  - `output.video.url` (string): URL of the generated video.
- `error` (object): Present if the job failed. `error.code` is the stable machine-readable value to branch on — one of `invalid_input`, `content_moderation`, `provider_error`, `provider_timeout`, `provider_unavailable`, `rate_limited`, `insufficient_balance`, `membership_required`, `cycle_limit_exceeded`, `admission_suspended`, `timed_out`, `internal`. Unrecognized values normalize to `provider_error`. `error.message` is diagnostic text and varies.

### Response

**200 OK · running**

```json
{
  "id": "media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0",
  "status": "running"
}
```

**200 OK · completed**

```json
{
  "id": "media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0",
  "status": "completed",
  "output": {
    "media_type": "video",
    "video": {
      "url": "https://api.dev.pika.art/v1/files/video_8f3a2c91.mp4",
      "content_type": "video/mp4"
    }
  }
}
```

**200 OK · failed**

```json
{
  "id": "media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0",
  "status": "failed",
  "error": {
    "code": "provider_error",
    "message": "upstream generation failed"
  }
}
```

## Get result

`GET /v1/media/jobs/{request_id}/content`

```bash
curl https://api.dev.pika.art/v1/media/jobs/{request_id}/content \
  -H "X-API-Key: YOUR_API_KEY"
```

Once the job completes, fetch a download URL for the generated media.

### Response

**200 OK · content URL**

```json
{
  "url": "https://api.dev.pika.art/v1/files/video_8f3a2c91.mp4"
}
```

## Errors

Errors use conventional HTTP status codes and always return JSON, in one of two shapes. Request-level errors (auth, unknown path, schema validation, idempotency conflict) are `{"message": "..."}`. Submit rejections that occur after the job row is created (insufficient balance, rate limit, unpriceable input, dispatch unavailable) return the full failed job envelope — branch on `error.code`, and retry with a fresh `Idempotency-Key`, since a failed job replays on its key.

- 401 Unauthorized — The API key is missing or invalid. Body: `{"message":"Invalid API key"}`
- 403 Forbidden — An inactive key is rejected with a `{"message"}` body. A submit that the org balance or postpaid cycle limit cannot cover is rejected after the job row exists and returns the failed job envelope. `GET /billing/balance` separates the two: a `200` means the key is active, so the rejection was the balance or the cycle limit. Body: `{"id":"media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0","status":"failed","error":{"code":"insufficient_balance","message":"Insufficient org balance"}}`
- 404 Not Found — No job with that id exists in your org, or the media path names an unknown vendor/model/function. Body: `{"message":"media job not found"}`
- 409 Conflict — The result was requested before the job completed, or an Idempotency-Key header was reused with a different body. Body: `{"message":"media job is not ready"}`
- 422 Unprocessable Entity — The request body failed validation: an invalid enum value, a missing required field, a wrong type, or malformed JSON. The JSON message names the offending field. A schema-valid parameter combination that cannot be priced instead fails after job creation and returns the failed job envelope with error code `invalid_input`. Body: `{"message":"duration: Input should be less than or equal to 15"}`
- 429 Too Many Requests — Org limit reached: requests per minute or day, or concurrent jobs. Returned as the failed job envelope; check the Retry-After header and retry with a fresh Idempotency-Key. Body: `{"id":"media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0","status":"failed","error":{"code":"rate_limited","message":"rate limit exceeded: rpm"}}`
- 503 Service Unavailable — The model rail or a backend dependency is temporarily unavailable. Returned as the failed job envelope; retry with backoff and a fresh Idempotency-Key. Body: `{"id":"media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0","status":"failed","error":{"code":"provider_unavailable","message":"media dispatch unavailable"}}`

## Pricing

- 480p: $0.0325 per second
- 720p: $0.065 per second
- 1080p: $0.13 per second

Only successful generations are charged.

Check the balance against this price before submitting: `GET https://api.dev.pika.art/billing/balance` returns `balance_micro_usd`, which is US dollars multiplied by 1,000,000, and `postpaid` when the org bills by invoice instead. For an active postpaid org, compare the price against `postpaid.cycle.remaining_micro_usd` rather than the prepaid balance. Report a shortfall to the user rather than submitting a request the balance cannot cover.

---

Model page: https://dev.pika.art/models/alibaba/wan3.0-video/text-to-video
API index: https://dev.pika.art/llms.txt