# Pika Speech

Fast voice-cloning text-to-speech.

- Model ID: `pika/pika-audio/pika-speech`
- Provider: Pika
- Modality: text → audio
- Type: Pika Speech
- Status: stable
- Delivery: async
- Output format: mp3

## 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-audio/pika-speech
```

## 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-audio/pika-speech`

```bash
curl -X POST https://api.dev.pika.art/v1/media/pika/pika-audio/pika-speech \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "script": "...",
  "voice_preset": "plummy_posh_gentleman",
  "seed": 6002,
  "voice_consent_attested": false
}'
```

### Request body

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `script` | string | yes | - | Script |
| `reference_audio` | string | no | - | Reference Audio |
| `voice_preset` | enum | no | - | Voice Preset |
| `seed` | integer | no | -1 | Seed |
| `voice_consent_attested` | boolean | no | false | Set true to attest that you have the rights and permissions needed to clone the voice in reference_audio. Required when reference_audio is supplied. |

### Accepted values

| Param | Values | Default |
| --- | --- | --- |
| `voice_preset` | `deep_trailer_bass`, `warm_honey_drawl`, `fast_talking_wiseguy`, `graceful_elder_storyteller`, `chill_surfer_dude`, `bubbly_it_girl`, `roaring_locker_room_coach`, `calm_documentary_narrator`, `velvet_radio_alto`, `gruff_slow_drawl`, `brassy_sharp_wit`, `vintage_radio_showman`, `gentle_hushed_librarian`, `rapid_sports_caller`, `warm_playful_spark`, `folksy_porch_storyteller`, `crisp_founder_pitch`, `smoky_noir_monotone`, `sunny_morning_host`, `cozy_grandpa_storyteller`, `plummy_posh_gentleman`, `cheeky_bright_charmer`, `rapid_market_banter`, `stern_clipped_headmistress`, `hearty_fireside_rumble`, `soft_thoughtful_lilt`, `musical_poetic_lilt`, `melodic_quick_storyteller`, `gravelly_deadpan`, `imperious_grande_dame`, `dry_cheerful_joker`, `polished_news_anchor`, `warm_grounded_friend`, `commanding_safari_guide`, `rhythmic_radio_charmer`, `mellow_wise_elder`, `lilting_warm_hostess`, `articulate_tech_lead`, `booming_epic_showman`, `cool_minimal_designer`, `precise_stern_engineer`, `breathy_chic_charm`, `slow_heavy_brooder`, `fiery_passionate_cook`, `loving_loud_grandma`, `gentle_careful_sweetness`, `velvet_worldly_narrator`, `deep_night_storyteller`, `bright_peppy_vlogger`, `poised_documentary_calm`, `grumpy_soft_heart`, `zany_kid_inventor`, `hammy_pirate_captain`, `theatrical_scheming_villain`, `slow_goofy_giant`, `wheezy_batty_wizard`, `raspy_scrappy_kid`, `chatty_beauty_bestie`, `hyped_gym_motivator`, `soft_cozy_aesthetic`, `smooth_hype_unboxer`, `bored_chic_trendsetter`, `joyful_food_fanatic`, `deadpan_ironic_fry`, `mellow_road_tripper`, `breathy_luxe_diva`, `fast_nerdy_reviewer`, `unhinged_arena_hype`, `abyssal_doom_growl`, `airhorn_club_mc`, `barking_drill_fury`, `smoky_mystic_drama`, `booming_ring_announcer`, `feather_whisper_asmr`, `seismic_boss_god`, `thunderous_revival_preacher` | — |

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): `audio`.
  - `output.audio.url` (string): URL of the generated audio.
- `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": "audio",
    "audio": {
      "url": "https://api.dev.pika.art/v1/files/audio_8f3a2c91.mp3",
      "content_type": "audio/mpeg"
    }
  }
}
```

**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/audio_8f3a2c91.mp3"
}
```

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

- default: $0.01 per minute

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. Report a shortfall to the user rather than submitting a request the balance cannot cover.

---

Model page: https://dev.pika.art/models/pika/pika-audio/pika-speech
API index: https://dev.pika.art/llms.txt