The Picacho API
Generate images of your own characters from your own software — the same pipeline the app uses, with the same identity locking and the same match scoring. Four endpoints, one key, and it draws on the credits already included in your plan.
Included with Elite. Create a key in Settings → Security. If you're on another plan and need it, get in touch — we enable it per account.
Authentication
Send your key as a bearer token on every request. Keys are shown once, when you create them — we store only a hash, so a lost key can't be recovered, only replaced.
curl https://picacho.ai/api/v1/usage \
-H "Authorization: Bearer pic_live_your_key_here"A first request, end to end
List your characters to get an id, then generate against it. That's the whole integration.
# 1. find your character
curl https://picacho.ai/api/v1/characters \
-H "Authorization: Bearer $PICACHO_KEY"
# 2. make an image of her
curl -X POST https://picacho.ai/api/v1/generations \
-H "Authorization: Bearer $PICACHO_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "walking through a snowy street at night",
"character_id": "11111111-2222-4333-8444-555555555555"
}'Your characters, newest first. has_identity_photo tells you which ones can hold a face — a character without one will still generate, but nothing anchors the likeness.
{
"characters": [
{
"id": "11111111-2222-4333-8444-555555555555",
"name": "Eva",
"traits": { "hair": "long red curls", "distinguishing_features": "freckles" },
"has_identity_photo": true,
"created_at": "2026-08-04T18:22:11.000Z"
}
]
}Makes one image and returns it when it's ready — typically 20 to 60 seconds, so set your client timeout accordingly. One credit per image. Picacho retries automatically before reporting a failure; if something goes wrong on our side, get in touch and we'll credit it back.
Body: prompt (required, up to 2000 characters) and character_id (optional — omit it and you get a generic image with no identity locking).
{
"id": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
"status": "succeeded",
"image_url": "https://picacho.ai/api/media/generated-images/...",
"final_prompt": "Eva walks along a narrow cobblestone street at night...",
"match_score": 91,
"credits_used": 1
}final_prompt is what actually ran after Picacho's drafting step expanded your sentence — usually the most useful thing to tune against. match_score is how closely the result matches the character's identity photo, 0–100; it's null when no character was used.
The image URL is permanent and needs no authentication, so you can store it, embed it, or hand it to a CDN.
Fetch a generation later. Useful if your HTTP client timed out before the POST returned — the work still finished on our side, and the result is here, including the same final_prompt, image_url and match_score the POST would have returned.
What's left this billing period. Worth calling before firing a large batch, so a budget ceiling shows up as one number rather than a wall of errors halfway through.
{
"plan": "elite",
"plan_label": "Elite",
"included_this_period": 1000,
"used_this_period": 42,
"remaining_this_period": 958,
"purchased_credits": 0,
"period_started_at": "2026-08-09T00:00:00.000Z"
}Two budgets, drawn in order: remaining_this_period is the monthly allowance included with the plan, and purchased_credits is a separate one-off balance (credit packs) that covers anything the monthly allowance can't and never resets. Generating stops with a 402 only once both are exhausted, so the real headroom before a batch is the sum of the two.
Errors and limits
Errors come back as { "error": { "code", "message" } } with a matching HTTP status: 401 for a missing, invalid or revoked key, 403 when the account doesn't have API access, 402 when you're out of credits, 404 for an id that isn't yours, and 429 past 30 requests per minute to POST /api/v1/generations. The limit counts requests, not finished images — a request refused with a 402 still consumes a slot — so a batch that runs out of credits mid-loop can hit 429s too. Back off for the number of seconds in the retry-after header.
Video isn't in this version. A render takes six to ten minutes and needs a queue rather than a request — if you need it, tell us and it moves up the list.
Use it from Claude, Cursor or any MCP client
The same four endpoints are also an MCP server, so an assistant can render your character directly. One endpoint, your same API key, and the same credits — nothing goes through a separate meter.
{
"mcpServers": {
"picacho": {
"url": "https://picacho.ai/api/mcp",
"headers": { "Authorization": "Bearer pic_live_your_key_here" }
}
}
}Four tools: list_characters, generate_image, get_generation and get_usage. Only generate_image spends credits, and it's marked that way so a client asks you first.
The reason it's worth connecting rather than calling a generic image API: generate_image comes back with match_score — how closely the rendered face matches your character's own photo. An assistant can read that number and try again on its own, instead of handing you a picture of someone else and calling it done.