Authentication

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

API Keys

API keys are created in your dashboard settings. Each key is associated with your team and has access to all team resources.

Creating an API Key

Navigate to Settings > API Keys in the dashboard
Click Create API Key
Give your key a descriptive name (e.g., “Production Server”, “Development”)
Copy the key immediately - it won’t be shown again

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

Using Your API Key

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

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

import { Pictify } from '@pictify/sdk';

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

from pictify import Pictify

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

client := pictify.NewClient(os.Getenv("PICTIFY_API_KEY"))

client = Pictify::Client.new(api_key: ENV['PICTIFY_API_KEY'])

Key Format

An API key is a single 64-character hex string — there are no key prefixes, 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, which shows the exact request and response for every endpoint.

Security Best Practices

Environment Variables

Never hardcode API keys. Use environment variables:

# .env
PICTIFY_API_KEY=your-64-character-api-key

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:

Create a new API key in the dashboard
Update your application to use the new key
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 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 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. A quota rejection carries a plain message:

{
  "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 workflow (CSV row or webhook) 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. 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":

{
  "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.

Team API Keys

API keys are scoped to your team. All team members share access to the same API keys and resources. To manage team members:

Go to Settings > Team
Invite members by email
Assign roles (Admin, Editor, Viewer)

Only Admins can create, view, and delete API keys.

Troubleshooting

Invalid API Key

{
  "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 deleted in the dashboard
Ensure you’re using the correct environment (test vs production)

Missing Authorization Header

{
  "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

Getting Started

Concepts

Security

Resources

Authentication

Authentication

API Keys

Creating an API Key

Using Your API Key

SDK Configuration

Key Format

Security Best Practices

Environment Variables

Server-Side Only

Key Rotation

Least Privilege

Rate Limits and Quotas

Credits

Render credits

AI credits

Team API Keys

Troubleshooting

Invalid API Key

Missing Authorization Header

​Authentication

​API Keys

​Creating an API Key

​Using Your API Key

​SDK Configuration

​Key Format

​Security Best Practices

​Environment Variables

​Server-Side Only

​Key Rotation

​Least Privilege

​Rate Limits and Quotas

​Credits

​Render credits

​AI credits

​Team API Keys

​Troubleshooting

​Invalid API Key

​Missing Authorization Header

Authentication

API Keys

Creating an API Key

Using Your API Key

SDK Configuration

Key Format

Security Best Practices

Environment Variables

Server-Side Only

Key Rotation

Least Privilege

Rate Limits and Quotas

Credits

Render credits

AI credits

Team API Keys

Troubleshooting

Invalid API Key

Missing Authorization Header