# Pika API for Agents

> Pika API provides callable model operations for image, video, audio, music, speech, transcription, dubbing, upscaling, and language models through one API key. Use this file to discover an operation, then read its linked specification before making a request.

The catalog and per-operation specifications are the runtime source of truth. Do not infer endpoint paths, request fields, enum values, pricing, or model support from a model name or from prior knowledge.

## Start Here

- [Create an account or sign in](https://dev.pika.art/login): Create a Pika API account, manage membership, and access the dashboard.
- [Dashboard](https://dev.pika.art/dashboard): Create and manage API keys, usage, and billing.
- [API keys](https://dev.pika.art/keys): Create, rotate, and revoke keys.
- [Webhooks](https://dev.pika.art/webhooks): Register callback endpoints and read the organization's signing secret.
- [Agent onboarding](https://dev.pika.art/agent): Copy the short Pika onboarding prompt into a coding agent, app builder, or chat assistant.
- [Models](https://dev.pika.art/models): Browse the human-readable model catalog and playgrounds.
- [Pricing](https://dev.pika.art/pricing): Review current model pricing before running paid generations.

## Getting started

Onboarding is self-serve end to end. No sales contact, no waitlist, no manual provisioning.

1. Create an account at https://dev.pika.art/login. Signing in creates the organization.
2. Generate an API key at https://dev.pika.art/keys, where keys are also rotated and revoked.
3. Add funds at https://dev.pika.art/billing. Generation is prepaid, so a submit fails with `insufficient_balance` until the org has a balance.
4. Call `GET https://api.dev.pika.art/catalog/apis` to confirm connectivity, then submit an operation.

Free to call, and the closest thing to a sandbox:

- The public catalog (`https://api.dev.pika.art/catalog/apis`) needs no API key.
- Quotes (`POST https://api.dev.pika.art/catalog/apis/{api_id}/quote`) and the balance and spend reads are never charged.

There is no free generation tier and no separate test environment. Every generation runs against production at the price the catalog quotes, so price a request before running it.

## Environments

- Documentation and model pages: `https://dev.pika.art`
- Customer API base URL: `https://api.dev.pika.art`
- OpenAPI 3.1 description: `https://dev.pika.art/openapi.json`. Declares the accepted authentication schemes and every callable path.
- Recommended local secret name: `PIKA_API_KEY`
- Authentication header: `X-API-Key: $PIKA_API_KEY` or `Authorization: Bearer $PIKA_API_KEY`. Google's `x-goog-api-key` is not accepted.

Never place an API key in browser code, a URL, source control, generated output, screenshots, or chat. Store it in the runtime's server-side secret manager or local environment. A browser application must call Pika through its own authenticated server route.

## Documentation Precedence

Use these sources in this order:

1. For current availability, request fields, required inputs, enum values, and pricing metadata, use `GET https://api.dev.pika.art/catalog/apis/{api_id}?expand=inputs`. Send the slashes in `api_id` literally (`bytedance/seedance-2.0/text-to-video`).
2. For the exact submit endpoint, request and response examples, polling behavior, uploads, and errors, use the operation's linked `https://dev.pika.art/llms/...` specification.
3. Use this `llms.txt` file for discovery and routing, not as a substitute for the selected operation's specification.

If a prose example conflicts with the catalog `input_schema`, follow the catalog schema. If an operation is missing from the public catalog or is not active, do not call it.

## Agent Workflow

1. Determine the user's intended output and available inputs: text, image, video, audio, or a combination.
2. Shortlist operations from the model list below. Recommend one best fit and, only when useful, one alternative. Explain the tradeoff in quality, speed, capability, or cost.
3. Fetch the selected operation's linked specification and its live catalog record before writing request code.
4. Check that `PIKA_API_KEY` is configured without printing or exposing it. If absent, guide the user to [sign in](https://dev.pika.art/login) and create a key in the dashboard.
5. Read the balance and confirm it covers the requests you are about to make. If it does not, report the shortfall and stop there.
6. State the selected model, operation, important settings, and number of paid requests before submitting. A user's approval of one generation does not authorize a batch or additional variants.
7. Execute the request, wait for a terminal result, save or integrate the output, and report the model used and the next recommended capability.

## Media API

All non-LLM generation operations use concrete asynchronous REST endpoints.

- Submit: `POST https://api.dev.pika.art/v1/media/{vendor}/{model}/{function}` using the exact path and JSON body from the selected operation's specification.
- The submit response returns a job object containing `id` and `status`. Preserve the returned `id` as the request ID.
- Poll: `GET https://api.dev.pika.art/v1/media/jobs/{request_id}` until `status` is `completed` or `failed`, or take a webhook instead.
- Result: a completed job carries its download URL in `output`. `GET https://api.dev.pika.art/v1/media/jobs/{request_id}/content` returns that same URL as `{ "url": "..." }` and answers `409` before the job completes.
- Delete: `DELETE https://api.dev.pika.art/v1/media/jobs/{request_id}` erases the job's stored media and the request captured at submit (the prompt and parameters), and answers `204`. The job then reports `deleted_at` in epoch seconds with no `output`, and the content endpoint answers `410`. A running job is `409` with `retry_after` seconds; a `503` still accepted the deletion, which finishes on its own. Repeats are safe.
- Cost: a terminal job carries `usage` (provider-reported units) and `billing`. Record spend from `billing.charge_micro_usd` only when `billing.state` is `settled`; `pending` means retry shortly, and `null` (submit responses, webhooks) is not a charge.

For retry-safe submits, send a stable `Idempotency-Key` for the same request body. Never reuse an idempotency key with a different body. A failed job replays on its key, so retry a failure with a fresh key.

## Language Model API

Language-model operations are synchronous. Fetch the selected model's specification before choosing a protocol.

- OpenAI-compatible: `POST https://api.dev.pika.art/v1/chat/completions`
- Anthropic Messages: `POST https://api.dev.pika.art/anthropic/v1/messages`
- Google GenAI: `POST https://api.dev.pika.art/genai/v1beta/models/{model}:generateContent`

Streaming is supported: send `"stream": true` on the OpenAI and Anthropic surfaces, and call `:streamGenerateContent` instead of `:generateContent` on GenAI.

Use only the protocol and model identifier from the selected model's specification.

## Errors and Retries

- `401`: API key missing or invalid. Stop and correct authentication.
- `403`: key inactive or balance insufficient, returned as the failed job envelope on a media submit. Branch on `error.code`, or read `GET https://api.dev.pika.art/billing/balance` to tell the two apart — a `200` means the key is active and the request was priced above the balance. Report the shortfall and direct the user to top up in the dashboard. Do not retry the same submit.
- `404`: operation, job, or file not found. Recheck the current catalog and request ID.
- `409`: result requested too early or an idempotency key was reused with a different body.
- `413` / `415`: upload too large, or an unsupported `content_type` on `/v1/media/uploads`.
- `422`: request validation or unpriceable parameter combination. Correct the request from the live schema; do not retry unchanged.
- `429`: rate or concurrency limit reached, returned as the failed job envelope on a media submit. Respect `Retry-After` and retry with bounded backoff.
- `502` / `504`: upstream provider failed or timed out; synchronous surfaces only.
- `503`: Pika-side dependency unavailable (auth, billing, or dispatch). Retry with bounded backoff; surface the failure if it persists.

Every error body is JSON. Request-level errors (auth, unknown path, schema validation, idempotency conflict) are `{"message": "..."}`.

Never silently switch models after a paid request fails. Explain the failure and obtain approval before submitting to a different model.

## Completion Standard

A successful integration ends with working code or a generated artifact, the selected model and operation recorded, the output URL saved or integrated, secrets kept server-side, and a clear next step. Do not stop after merely describing the API.

API index: https://dev.pika.art/llms.txt