# Pika H3 Flex

Generate a video with synchronized audio from a text prompt. Choose any whole-second duration from 5 to 15, 480p or 768p resolution, and one of 11 aspect ratios. Optionally rewrite the prompt. 1080p/2k/4k generates at 768p and upscales once with Pika Upsampler V1, preserving audio and frame rate. Combined pricing is per actual output second; the quote reserves the native frame-count duration bound.

- Model ID: `pika/pika-h3-flex/text-to-video`
- Provider: Pika
- Modality: text → video
- Type: Text to Video
- Status: stable
- Delivery: async
- Max resolution: 4k
- Output format: mp4
- Aspect ratios: auto, 21:9, 16:9, 3:2, 4:3, 5:4, 1:1, 4:5, 3:4, 2:3, 9:16, 9:21

## 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/pika/pika-h3-flex/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/pika/pika-h3-flex/text-to-video`

```bash
curl -X POST https://api.dev.pika.art/v1/media/pika/pika-h3-flex/text-to-video \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "A large working vegetable farm under a soft overcast sky, pale grey-white cloud with patches of soft blue. Endless parallel rows of raised beds of dark brown tilled soil, clumpy and freshly turned, each lined with tall pale bamboo cane A-frame teepees tied with twine at the top, young leafy green tomato and pepper seedlings at their base, terracotta pots along low weathered grey timber bed edges, a line of green crops on the far flat horizon.\n\nThe video opens with NO person visible. The first four seconds show only rows of plants and bamboo.\n\nShot 1, one continuous camera move:\n0-4s: The camera is low, at waist height, and trucks sideways to the right at high speed, travelling perpendicular to the rows. Row after row after row of bamboo teepees and green plants rushes across the frame from right to left, each row flashing past one after another: canes, plants, gap of soil, canes, plants, gap of soil. Strong motion blur on the foreground canes, the horizon steady. Like a camera car racing along the end of the field.\n4-5s: The camera brakes hard and stops dead, perfectly lined up looking straight down the length of one single row, the row's soil path running to a vanishing point in the centre of frame. A tiny silver figure is just visible far away at the end of the row. A brief still beat.\n5-8s: The camera launches forward and dollies fast and low straight down that row between the bamboo canes, the canes streaming past either side. It decelerates as the figure grows into a woman kneeling in the soil and stops in a medium-wide side-on shot of her: early 30s, pale skin with a few freckles, dark brown hair in a low loose chignon, a calm focused expression, wearing a dramatic Victorian-silhouette ballgown made of crinkled glossy SILVER metallic tarpaulin, with a deep V neckline, enormous puffed short sleeves, a gathered waist and a huge skirt pooled and spread across the soil behind her. She leans forward on one hand over the bed, planting a small seedling with a steel hand trowel with a wooden handle.\n\nHard cut.\n\nShot 2:\n8-12s: Tight close-up at soil level on her hands. She presses dark damp soil firmly around the base of the seedling and pats it down twice, sets the trowel aside, then brushes her palms together to dust them off. Crumbs of soil fall from her fingers. The glossy crinkled silver plastic of her skirt fills the background.\n\nThe silver plastic gown has real stiffness: it crackles, creases and catches soft highlights. Soil is clumpy and leaves dirt on her fingers. Soft diffused overcast light, no hard sun or hard-edged shadows, but rich contrast and dimension. Surreal fashion-editorial tone played straight. Photographic natural colour, subtle film grain. The woman and her gown stay exactly the same; nothing morphs. SPEED IS CRITICAL: everything moves at normal real-time speed, like 24fps footage played back at 24fps - natural motion, NO slow motion.\n\nSound: natural diegetic location sound only — rushing wind and whoosh of canes flashing past, then quiet wind through leaves, the crinkle of the plastic gown, trowel scraping soil, soft pats, dry hands brushing together. No music, no score, no singing, no melody, no rhythm track.",
  "duration": 12,
  "resolution": "2k",
  "seed": 0,
  "rewrite": true,
  "output_mode": "video",
  "channel_mode": "stereo"
}'
```

### Request body

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `prompt` | string | yes | - | Prompt |
| `duration` | integer (5 – 15) | no | 5 | Video duration in whole seconds, from 5 to 15. |
| `aspect_ratio` | enum | no | - | Output aspect ratio. Auto selects from the original prompt and reference video, even when rewrite is false; with a keyframe it follows the first supplied keyframe. A fixed ratio always wins. When omitted, rewriting enables Auto; without rewriting, the first supplied keyframe sets the ratio, or 16:9 without a keyframe. Keyframes are resized and center-cropped to fit. |
| `resolution` | enum | no | 768p | 480p/768p are native. 1080p/2k/4k generates at 768p, then upscales once with the V1 model, preserving audio and frame rate. |
| `seed` | integer (0 – 9223372036854776000) | no | 0 | Seed |
| `rewrite` | boolean | no | true | Improve the prompt before generation; disable to use the original prompt. |
| `output_mode` | enum | no | video | audio-stems (Flex in production, every H3 family in staging) returns the original video with audio plus Dialogue, Score, SFX, Foley and Ambience WAV files. Uses standard retention and adds the catalog's separation fee. Flex bills the sum of all decoded output-stem durations, without a channel multiplier. The default returns only the video. |
| `channel_mode` | enum | no | stereo | Audio stems only: stereo preserves both channels; mono downmixes before separation. The video's audio is unchanged. |

#### Example body

```json
{
  "prompt": "A large working vegetable farm under a soft overcast sky, pale grey-white cloud with patches of soft blue. Endless parallel rows of raised beds of dark brown tilled soil, clumpy and freshly turned, each lined with tall pale bamboo cane A-frame teepees tied with twine at the top, young leafy green tomato and pepper seedlings at their base, terracotta pots along low weathered grey timber bed edges, a line of green crops on the far flat horizon.\n\nThe video opens with NO person visible. The first four seconds show only rows of plants and bamboo.\n\nShot 1, one continuous camera move:\n0-4s: The camera is low, at waist height, and trucks sideways to the right at high speed, travelling perpendicular to the rows. Row after row after row of bamboo teepees and green plants rushes across the frame from right to left, each row flashing past one after another: canes, plants, gap of soil, canes, plants, gap of soil. Strong motion blur on the foreground canes, the horizon steady. Like a camera car racing along the end of the field.\n4-5s: The camera brakes hard and stops dead, perfectly lined up looking straight down the length of one single row, the row's soil path running to a vanishing point in the centre of frame. A tiny silver figure is just visible far away at the end of the row. A brief still beat.\n5-8s: The camera launches forward and dollies fast and low straight down that row between the bamboo canes, the canes streaming past either side. It decelerates as the figure grows into a woman kneeling in the soil and stops in a medium-wide side-on shot of her: early 30s, pale skin with a few freckles, dark brown hair in a low loose chignon, a calm focused expression, wearing a dramatic Victorian-silhouette ballgown made of crinkled glossy SILVER metallic tarpaulin, with a deep V neckline, enormous puffed short sleeves, a gathered waist and a huge skirt pooled and spread across the soil behind her. She leans forward on one hand over the bed, planting a small seedling with a steel hand trowel with a wooden handle.\n\nHard cut.\n\nShot 2:\n8-12s: Tight close-up at soil level on her hands. She presses dark damp soil firmly around the base of the seedling and pats it down twice, sets the trowel aside, then brushes her palms together to dust them off. Crumbs of soil fall from her fingers. The glossy crinkled silver plastic of her skirt fills the background.\n\nThe silver plastic gown has real stiffness: it crackles, creases and catches soft highlights. Soil is clumpy and leaves dirt on her fingers. Soft diffused overcast light, no hard sun or hard-edged shadows, but rich contrast and dimension. Surreal fashion-editorial tone played straight. Photographic natural colour, subtle film grain. The woman and her gown stay exactly the same; nothing morphs. SPEED IS CRITICAL: everything moves at normal real-time speed, like 24fps footage played back at 24fps - natural motion, NO slow motion.\n\nSound: natural diegetic location sound only — rushing wind and whoosh of canes flashing past, then quiet wind through leaves, the crinkle of the plastic gown, trowel scraping soil, soft pats, dry hands brushing together. No music, no score, no singing, no melody, no rhythm track.",
  "duration": 12,
  "resolution": "2k",
  "seed": 0,
  "rewrite": true,
  "output_mode": "video",
  "channel_mode": "stereo"
}
```

### Accepted values

| Param | Values | Default |
| --- | --- | --- |
| `aspect_ratio` | `auto`, `21:9`, `16:9`, `3:2`, `4:3`, `5:4`, `1:1`, `4:5`, `3:4`, `2:3`, `9:16`, `9:21` | — |
| `resolution` | `480p`, `768p`, `1080p`, `2k`, `4k` | `768p` |
| `output_mode` | `video`, `audio-stems` | `video` |
| `channel_mode` | `stereo`, `mono` | `stereo` |

Returns a job object, not the final output — normally with status `queued`. If you're at your concurrency limit, the job stays `queued` until a slot frees up, then starts on its own. 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.
- `usage` (object): Units the provider reported for the job, such as `video_output_tokens`, `image_output_tokens`, `input_tokens`, or `output_seconds`. Present once the job is terminal, carries only the units the job reports, and is `null` when nothing was reported. It may not reproduce the charge, because some pricing components are fixed by the request; the charge is authoritative.
- `billing` (object): What the job charged. Present once the job is terminal, `null` on the submit response and on webhooks. `billing.state` is one of `settled`, `pending`, `unavailable`. `settled` carries `charge_micro_usd`, the amount collected in micro-USD (the balance's unit), `0` included. `pending` means the charge is still settling: retry at 1s, 2s, then 5s. `unavailable` means the billing read failed on Pika's side: retry no sooner than 30s. Record spend only when `state` is `settled`, keyed by job id; a `billing` of `null` is not a charge.

### 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"
    }
  },
  "usage": {
    "video_output_tokens": 50638
  },
  "billing": {
    "state": "settled",
    "charge_micro_usd": 372189
  }
}
```

**200 OK · failed**

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

A completed job carries its download URL in `output`. `GET /v1/media/jobs/{request_id}/content` returns that same URL as `{ "url": "..." }` for clients that only kept the id; it answers `409` until the job completes.

## 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 — You've hit your per-minute or per-day request limit, or your org's job queue is full. Returned as the failed job envelope. If there's a Retry-After header, wait that long, then 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.01 per second
- 768p: $0.02 per second
- 1080p: $0.035 per second
- 2k: $0.04 per second
- 4k: $0.08 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/pika/pika-h3-flex/text-to-video
API index: https://dev.pika.art/llms.txt