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

# API Overview

> Pictify API reference and conventions

# API Overview

The Pictify API is a RESTful JSON API for generating images, GIFs, and PDFs programmatically.

## Base URL

```
https://api.pictify.io
```

## Authentication

All requests require a Bearer token:

```bash theme={null}
curl https://api.pictify.io/image \
  -H "Authorization: Bearer YOUR_API_KEY"
```

See [Authentication](/authentication) for details.

## Request Format

* Content-Type: `application/json`
* Request bodies are JSON
* Dates use ISO 8601 format

```bash theme={null}
curl -X POST https://api.pictify.io/image \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<h1>Hello World</h1>",
    "width": 1200,
    "height": 630
  }'
```

## Response Format

Successful responses return JSON with relevant data:

```json theme={null}
{
  "url": "https://cdn.pictify.io/renders/abc123.png",
  "id": "img_abc123",
  "width": 1200,
  "height": 630,
  "createdAt": "2026-01-29T10:30:00Z"
}
```

Error responses are plain JSON with a human-readable message under `message` or `error` (see [Error Handling](/api-reference/errors) for every shape):

```json theme={null}
{
  "message": "Template not found"
}
```

## Rate Limits and Credits

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

* **Monthly credits** — every render (image, GIF, PDF page, video) consumes credits. When they run out, the **image, GIF, HTML-template and batch endpoints return `429`** with `code: "quota_exceeded"`, while the **video and workflow 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.

## Pagination

List endpoints return paginated results:

```bash theme={null}
curl "https://api.pictify.io/templates?page=2&limit=20" \
  -H "Authorization: Bearer $API_KEY"
```

Response includes pagination metadata:

```json theme={null}
{
  "templates": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 45,
    "totalPages": 3,
    "hasNext": true,
    "hasPrev": true
  }
}
```

## HTTP Status Codes

| Code | Description |
| - | - |
| 200 | Success |
| 201 | Created |
| 202 | Accepted (async operation started) |
| 400 | Bad Request (validation error) |
| 401 | Unauthorized (invalid API key) |
| 403 | Forbidden (access denied) |
| 404 | Not Found |
| 422 | Unprocessable Entity |
| 429 | Rate Limit Exceeded |
| 500 | Internal Server Error |

## Idempotency

POST requests can include an `Idempotency-Key` header for safe retries:

```bash theme={null}
curl -X POST https://api.pictify.io/image \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: unique-request-id-123" \
  -H "Content-Type: application/json" \
  -d '{"html": "..."}'
```

The same key with the same request will return the cached response for 24 hours.

## Versioning

The API does not currently use URL-based versioning. All endpoints are accessed directly from the base URL. Breaking changes will be communicated in advance via release notes.

## SDK Libraries

Official SDKs handle authentication, retries, and error handling:

* [Node.js SDK](/sdks/nodejs)
* [Python SDK](/sdks/python)
* [Go SDK](/sdks/go)
* [Ruby SDK](/sdks/ruby)

## Endpoints

### Generation

| Endpoint | Method | Description |
| - | - | - |
| `/image` | POST | [Generate an image](/api-reference/generation/images) |
| `/image/canvas` | POST | [Image from FabricJS canvas](/api-reference/generation/images#canvas) |
| `/image/agent-screenshot` | POST | [AI-powered screenshot](/api-reference/generation/images#agent-screenshot) |
| `/templates/{uid}/render` | POST | [Render template to image](/api-reference/templates#render) |
| `/gif` | POST | [Generate a GIF](/api-reference/generation/gifs) |
| `/gif/capture` | POST | [Capture GIF from URL](/api-reference/generation/gifs#capture) |
| `/pdf/render` | POST | [Generate a PDF](/api-reference/generation/pdfs) |
| `/pdf/multi-page` | POST | [Multi-page PDF](/api-reference/generation/pdfs#multi-page) |

### Templates

| Endpoint | Method | Description |
| - | - | - |
| `/templates` | GET | [List templates](/api-reference/templates#list) |
| `/templates` | POST | [Create template](/api-reference/templates#create) |
| `/templates/{uid}` | GET | [Get template](/api-reference/templates#get) |
| `/templates/{uid}` | PUT | [Update template](/api-reference/templates#update) |
| `/templates/{uid}` | DELETE | [Delete template](/api-reference/templates#delete) |
| `/templates/{uid}/render` | POST | [Render template](/api-reference/templates#render) |
| `/templates/{uid}/variables` | GET | [Get variables](/api-reference/templates#variables) |

### Batch Operations

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{uid}/batch-render` | POST | [Start batch job](/api-reference/batch#create) |
| `/templates/batch/{id}/results` | GET | [Get batch results](/api-reference/batch#results) |
| `/templates/batch/{id}/cancel` | POST | [Cancel batch](/api-reference/batch#cancel) |

### Webhooks

| Endpoint | Method | Description |
| - | - | - |
| `/webhook-subscriptions` | GET | [List subscriptions](/api-reference/webhooks#list) |
| `/webhook-subscriptions` | POST | [Create subscription](/api-reference/webhooks#create) |
| `/webhook-subscriptions/{uid}` | GET | [Get subscription](/api-reference/webhooks#get) |
| `/webhook-subscriptions/{uid}` | PUT | [Update subscription](/api-reference/webhooks#update) |
| `/webhook-subscriptions/{uid}` | DELETE | [Delete subscription](/api-reference/webhooks#delete) |

### Bindings

| Endpoint | Method | Description |
| - | - | - |
| `/bindings` | GET | [List bindings](/api-reference/bindings#list) |
| `/bindings` | POST | [Create binding](/api-reference/bindings#create) |
| `/bindings/{uid}` | GET | [Get binding](/api-reference/bindings#get) |
| `/bindings/{uid}` | PUT | [Update binding](/api-reference/bindings#update) |
| `/bindings/{uid}` | DELETE | [Delete binding](/api-reference/bindings#delete) |


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