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

# Authentication

> Secure your API requests with API keys

# Authentication

All API requests require authentication using an API key passed in the `Authorization` header.

## API Keys

API keys are created on the [Settings page](https://pictify.io/dashboard/api-token) of the dashboard. A key belongs to your account — or to your team, if you have one — and has access to everything that account owns.

### Creating an API Key

1. Open **Settings** in the dashboard rail
2. Click **New key**
3. Copy the key with the **Copy** button. The list shows it masked (`pic_live_…3f2a9`), but the button always copies the full value, so you can come back for it later.

<Warning>
  API keys provide full access to your account. Keep them secure and never expose them in client-side code.
</Warning>

## Using Your API Key

Include your API key in the `Authorization` header as a Bearer token:

```bash theme={null}
curl -X POST https://api.pictify.io/image \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1>Hello</h1>"}'
```

### SDK Configuration

<CodeGroup>
  ```typescript Node.js theme={null}
  import { Pictify } from '@pictify/sdk';

  const pictify = new Pictify({
    apiKey: process.env.PICTIFY_API_KEY
  });
  ```

  ```python Python theme={null}
  from pictify import Pictify

  client = Pictify(api_key=os.environ["PICTIFY_API_KEY"])
  ```

  ```go Go theme={null}
  client := pictify.NewClient(os.Getenv("PICTIFY_API_KEY"))
  ```

  ```ruby Ruby theme={null}
  client = Pictify::Client.new(api_key: ENV['PICTIFY_API_KEY'])
  ```
</CodeGroup>

## Key Format

Keys created today start with `pic_live_` followed by 64 hex characters, so a key can be told apart from any other hex string in logs, support tickets and secret scanners. Keys created before September 2026 are bare 64-character hex strings; they keep working and do not need to be rotated.

There are no key types or sandbox keys. Every key is a live key: requests made with it render real assets and count against your plan's monthly credits.

To test without spending credits, use the free tier's included credits or the [API Playground](https://pictify.io/dashboard/api-playground), which shows the exact request and response for every endpoint.

## Security Best Practices

### Environment Variables

Never hardcode API keys. Use environment variables:

```bash theme={null}
# .env
PICTIFY_API_KEY=pic_live_...
```

### Server-Side Only

API keys should only be used in server-side code. Never include them in:

* Client-side JavaScript
* Mobile apps
* Public repositories
* Browser localStorage/cookies

### Key Rotation

If you suspect a key has been compromised:

1. Create a new API key in the dashboard
2. Update your application to use the new key
3. Delete the compromised key

### Least Privilege

Create separate API keys for different environments and services:

* Production server
* Staging server
* CI/CD pipeline
* Local development

## Rate Limits and Quotas

Two separate limits apply, and — for historical reasons — they surface under different status codes per endpoint family:

* **Monthly credits** — every render (image, GIF, PDF, video) consumes render credits; see [Credits](#credits) below for what each operation costs. When they run out, the **image, GIF, HTML-template and batch endpoints return `429`** with `code: "quota_exceeded"`, while the **video endpoints return `402`** with the same code. Treat `quota_exceeded` as "wait for the monthly reset or upgrade" — never as "retry with backoff": no amount of retrying refills a monthly quota.
* **Per-endpoint rate limits** — a few endpoints (unauthenticated public rendering, template previews) carry fixed per-minute limits. These return `429` *without* a `quota_exceeded` code and DO send standard `x-ratelimit-*` headers and `retry-after` — those are genuinely retryable after backing off.

So the rule for `429` is: **check the `code` field first.** `quota_exceeded` means credits, not rate.

A quota rejection carries a plain message:

```json theme={null}
{
  "message": "You've used all your renders for this month. Upgrade your plan to unlock more, or hang tight until next month!"
}
```

Handle `402` (quota) and `429` (rate) by backing off and surfacing the `message` to your logs — there is no machine-readable retry hint.

## Credits

Your plan carries **two separate monthly pools**. They never mix: renders spend our own rendering compute, while AI operations spend metered third-party AI services, so each is budgeted in its own currency.

### Render credits

Every render costs **1 render credit** — one image, one GIF, one PDF, one video render, one item in a batch. The single exception is GIF capture from a live URL (`POST /gif/capture`), which costs **1.5 render credits** because it records a headless browser session.

Monthly render allowances per plan are listed on the [pricing page](https://pictify.io/pricing). Paid plans can enable overage billing to keep rendering past the allowance.

### AI credits

All AI operations draw from **one** AI credit pool — there are no separate per-feature AI allowances:

| Operation | Cost |
| - | - |
| Copilot instruction — template editor or video studio (design, execute and review rounds all included) | 1 AI credit |
| AI code edit of a template | 1 AI credit |
| AI video generation (brief, scene code, compile, visual review, poster) | 5 AI credits |
| Transcription / captions | 1 AI credit per started minute of audio |

Monthly AI credit allowances per plan:

| Plan | AI credits / month |
| - | - |
| Free | 25 |
| Basic | 300 |
| Pro | 1,000 |
| Business | 4,000 |
| Business Plus | 6,000 |

Billing rules, in your favor:

* **Charged per user intention, not per internal step.** One copilot instruction is 1 credit even if it runs many model rounds internally.
* **Failures are never billed.** Credits are checked before an operation starts and spent only after it succeeds.
* **Silence is never billed.** Transcribing a clip in which no speech is found costs nothing (the request returns `422` with `code: "no_speech"`). When speech is found, minutes are counted up to the last spoken word, not the full clip length.
* **Renders inside AI operations are included.** Review frames and posters generated during an AI operation are part of its AI price — they do not also consume render credits.

AI credits reset on the first of each calendar month. There is no overage billing for AI credits: when the pool is exhausted, AI endpoints return **`402`** with `code: "ai_quota_exceeded"`:

```json theme={null}
{
  "message": "You've used this month's AI credits. Upgrade your plan for more, or they reset next month.",
  "code": "ai_quota_exceeded"
}
```

Your current balance for both pools is shown on the dashboard's usage meter, and the AI balance is included in the `aiCredits: { used, limit }` field of the plan details endpoint.

## Teams

Teams are optional. A solo account owns its keys outright. If you create a team, keys belong to the team and every member calls the API with the same keys and sees the same templates and renders. Invite members from **Team** in the dashboard.

## Troubleshooting

### Invalid API Key

```json theme={null}
{
  "type": "https://docs.pictify.io/errors/invalid-api-key",
  "title": "Invalid API Key",
  "status": 401,
  "detail": "The provided API key is invalid or has been revoked."
}
```

**Solutions:**

* Verify the key is copied correctly (no extra spaces)
* Check if the key has been revoked in the dashboard
* Make sure you copied the whole key, including the `pic_live_` prefix

### Missing Authorization Header

```json theme={null}
{
  "type": "https://docs.pictify.io/errors/missing-auth",
  "title": "Missing Authentication",
  "status": 401,
  "detail": "No API key provided. Include your API key in the Authorization header."
}
```

**Solutions:**

* Add the `Authorization: Bearer {api_key}` header
* Check for typos in the header name


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.