API
The Airbrush API
Generate images from a prompt, or pull social video research into your own tools. JSON in, JSON out, with the credit cost on every response. Included in all plans.
Overview
Two APIs, one base URL
Base URL: https://api.airbrush.ai
Image generation
POST /v1/imagescreates one image from a text prompt.Social video research
Breakout videos, trends, long-running ads, shop products, creator stats, full reports and view predictions.
Quickstart
Two calls to try
Generate an image
curl -X POST https://api.airbrush.ai/v1/images \
-H "Authorization: Bearer YOUR_IMAGE_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "studio product photo of a ceramic mug on a white background",
"ai_engine": "flux",
"image_dimensions": "large"
}'
The response includes the image URL, credits used and credits remaining. Image credits are charged after the image is made.
Find breakout videos for a keyword
curl "https://api.airbrush.ai/v1/outliers?q=coffee%20gadgets&window=30d" \
-H "Authorization: Bearer YOUR_RESEARCH_KEY"
Successful responses use { ok, data, meta }. meta.credits shows what was charged and your balance.
Reference
Endpoints and credit costs
| Endpoint | What it returns | Credits |
|---|---|---|
POST /v1/images | One generated image from a prompt | Varies by engine and size, reported in the response |
GET /v1/outliers | Breakout videos for a keyword, scored against a creator or niche median | 10 (cached 1) |
GET /v1/trends | Emerging, peaking or cooling hooks, formats, hashtags and sounds | 2 |
GET /v1/ads | Long-running ads for a keyword or brand | 6 (cached 1) |
GET /v1/products | Shop listings with estimated 7-day units, saturation and look-alikes | 15 (cached 1) |
GET /v1/creators/{platform}/{handle} | Creator median views, posting cadence, breakouts and best posts | 3 (cached 1) |
POST /v1/research | Full report with insights, outliers, hooks, formats and rising searches | 32 (cached 1) |
POST /v1/predict | Likely views range for a post link or script, with 3 to 5 suggested fixes | 10 |
GET /v1/jobs/{id}, /v1/reports/{id}, /v1/insights/{id} | Job status, or re-read a report or insight card | Free |
Estimates in research responses are labelled as estimates, and each answer lists its sources and a confidence score.
Production use
Built to be called from code
Credits on every call
meta.creditsreports charged and balance. Failed calls are refunded.Safe retries
Send an
Idempotency-Key(8 to 64 characters) on research and predict calls.Async jobs
Long runs return 202 with a poll URL, or use a signed webhook (
job.completed,job.failed, HMAC-SHA256 inAirbrush-Signature).Clear errors
{ ok: false, error: { code, message } }, with 429 andRetry-Afterwhen you send too fast.OpenAPI 3.1
Free, no key, at api.airbrush.ai/openapi.json.
Machine-readable docs
llms.txt for AI assistants.
Pricing
The API is in every plan
Calls draw on your Airbrush credits, which renew on the 1st. See pricing for the plans.
Using an AI assistant? The research endpoints also run as an MCP server for Claude, Cursor and other MCP clients.
API FAQ
Questions about the API
How do I authenticate?
Send your key as a Bearer token in the Authorization header, or in the X-API-Key header. Research keys start with mxk_. The image endpoint uses the image key from your account API page and also accepts it in the request body. Never put a key in the query string.
Which plans include the API?
The API is included in all plans. Calls use your Airbrush credits.
How is the API priced?
API calls use credits. Each response reports the credits charged and your remaining balance. Cached research answers cost 1 credit, polling a job is free, and failed calls are refunded.
Can I retry a request safely?
Research and predict calls accept an Idempotency-Key header of 8 to 64 characters, so a retry is not charged twice.
Are there webhooks?
Yes. Longer research runs return HTTP 202 with a job you can poll, or you can register a webhook for job.completed and job.failed events. Webhooks are signed with HMAC-SHA256 in the Airbrush-Signature header.
Is there an OpenAPI spec?
Yes. The OpenAPI 3.1 spec is free and needs no key, at https://api.airbrush.ai/openapi.json.