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

> Core concepts, authentication, and response patterns

## Purpose

The Percify API lets you programmatically generate images, transform them into videos, synthesize voice audio, and retrieve published media assets. All endpoints follow predictable credit-based metering.

## Base URL

```
https://api.percify.io/v1
```

## Authentication

Use an API key in the `Authorization` header:

```
Authorization: Bearer <API_KEY>
```

Keys are scoped per user account. Rotate periodically and never embed client-side.

## Common Endpoints

| Action           | Method | Path                |
| ---------------- | ------ | ------------------- |
| Generate Image   | POST   | /images/generate    |
| Video From Image | POST   | /videos/from-image  |
| Clone Voice      | POST   | /voices/clone       |
| Generate Audio   | POST   | /audio/generate     |
| Avatar Metadata  | GET    | /avatars/{avatarId} |
| Credit Balance   | GET    | /credits/balance    |

## Response Pattern

Successful async generation requests return a processing object:

```json theme={null}
{
  "id": "img_123",
  "status": "processing",
  "creditCost": 5,
  "createdAt": "2025-11-24T12:34:56Z"
}
```

Poll the status endpoint (same resource path) until `status` becomes `completed`.

## Errors

| Status | Meaning      | Typical Cause                             |
| ------ | ------------ | ----------------------------------------- |
| 400    | Bad request  | Missing required field / invalid duration |
| 401    | Unauthorized | Missing or bad API key                    |
| 403    | Forbidden    | Banned user or restricted asset           |
| 404    | Not found    | Invalid resource id                       |
| 429    | Rate limited | Too many requests in window               |
| 500    | Server error | Internal failure; retry later             |

## Idempotency (Recommended)

For operations that could be retried (e.g., payment intent creation), include an `Idempotency-Key` header. Future endpoints may enforce uniqueness for safety.

## Webhooks (Planned)

Upcoming event types:

* `avatar.generated`
* `video.completed`
* `audio.completed`
* `credits.updated`

## OpenAPI Specification

The full schema resides in `api-reference/openapi.json`. Use it to generate client SDKs or validate requests.

## Next Steps

* Review authentication details at \[/percify/api-auth]
* Explore endpoint examples in the API Reference tab
* Learn credit cost formulas at \[/percify/credits]

***

Need a new endpoint? Request via support with use case details.