> ## Documentation Index
> Fetch the complete documentation index at: https://docs.percify.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Percify API: base URL, keys and plans

> The Percify REST API runs image, video and voice models at api.percify.io/v3/playground/v1 with a pk_live key. Keys come with Scale and Ultra.

The Percify API lets your code run the same image, video and voice models as the Percify app, including talking avatar lip-sync and voice cloning. You send a model id and its inputs to `https://api.percify.io/v3/playground/v1/run` with an API key, then read the result from the generation. API keys come with the Scale and Ultra plans, and every call spends credits from your Percify balance.

## Base URL

```text theme={"system"}
https://api.percify.io/v3/playground/v1
```

Every request needs the header `Authorization: Bearer pk_live_…`. See [Authenticate Percify API requests](/percify/api-auth).

Successful responses wrap the result in a `data` object:

```json theme={"system"}
{ "success": true, "data": { "id": "…", "status": "processing" } }
```

## Endpoints

| Method | Path                   | What it does                                                                | Auth    |
| ------ | ---------------------- | --------------------------------------------------------------------------- | ------- |
| `POST` | `/v1/run`              | [Start a generation](/api-reference/generations/run)                        | API key |
| `GET`  | `/v1/generations/{id}` | [Read a generation's status and output](/api-reference/generations/get)     | API key |
| `POST` | `/v1/estimate`         | [Price a run without spending credits](/api-reference/generations/estimate) | API key |
| `GET`  | `/v1/models`           | [List every model and its inputs](/api-reference/models)                    | None    |
| `GET`  | `/v1/models/{id}`      | [One model's input schema](/api-reference/models)                           | None    |
| `GET`  | `/v1/openapi.json`     | OpenAPI 3.1 document for run and poll                                       | None    |
| `GET`  | `/v1/llms.txt`         | Plain-text catalog for agents                                               | None    |

Two longer pipelines have their own endpoints on the same host:

* `https://api.percify.io/v3/replicate/v1`: [analyze a short video and render a replica](/api-reference/video-studio/overview).
* `https://api.percify.io/v3/mascot/api`: [make a finished short video from a topic](/api-reference/short-videos).

AI agents can use the same account through the [Percify MCP server](/mcp-server) at `https://mcp.percify.io/mcp`.

## Who can use the API?

You can create API keys on the **Scale** and **Ultra** plans. On other plans, creating a key fails with `403` and the message `API access is available on the Scale plan. Upgrade to create API keys.`

API usage draws on the same monthly credits as the app: 3,000 credits a month on Scale and 8,000 on Ultra. Plan prices and billing are explained in [Plans and payments](/percify/payments). When you need more credits, use **Top up credits** on the developer page.

## How do I get an API key?

<Steps>
  <Step title="Open the developer page">
    Sign in at [app.percify.io](https://app.percify.io), open the account menu at the bottom of the sidebar and choose **API Access**. This opens [app.percify.io/home/developer](https://app.percify.io/home/developer).
  </Step>

  <Step title="Create the key">
    Click **New key**. Optionally add a name, pick an expiry (**Never expires**, **Expires in 30 days**, **Expires in 90 days** or **Expires in 1 year**) and set a **Monthly credit cap**. Then click **Create key**.
  </Step>

  <Step title="Copy it once">
    The full `pk_live_` key is shown only once. Store it in a secret manager or an environment variable on your server.
  </Step>
</Steps>

## How billing works for API calls

* A run's credits are taken when it starts. The response includes `creditsSpent`.
* If the run fails or times out, the credits go back to your balance automatically.
* Prices depend on the model and its inputs. Lip-sync is billed per second of audio, and some models change price with quality or resolution. Call [`POST /v1/estimate`](/api-reference/generations/estimate) to get the exact number first.
* A key's **Monthly credit cap** stops that key from spending more than the cap in a calendar month.

## Limits at a glance

| Limit                         | Value                               |
| ----------------------------- | ----------------------------------- |
| Requests per API key          | 60 per minute                       |
| Generation starts per account | 60 per minute                       |
| Per-key spend                 | Your **Monthly credit cap**, if set |

Details and error bodies are in [Errors and rate limits](/api-reference/errors-and-limits).

<Note>
  Call the API from your server. Browsers on other websites cannot call `api.percify.io` directly, and a key in front-end code can be copied by anyone.
</Note>

## Related

<CardGroup cols={2}>
  <Card title="Authenticate requests" href="/percify/api-auth">
    Send your pk\_live key, rotate it and cap its spend.
  </Card>

  <Card title="Code examples" href="/guides/sdk-integration">
    Node.js, Python and cURL, start to finished file.
  </Card>

  <Card title="Make a talking avatar video" href="/api-reference/avatars/overview">
    Image, voice and lip-sync in three calls.
  </Card>

  <Card title="MCP server" href="/mcp-server">
    Use Percify from Claude, ChatGPT, Cursor or Codex.
  </Card>
</CardGroup>