The Picacho API
Generate images of your own characters from your own software — the same pipeline the app uses: the character's own photos ride with every request, and the face is checked the same way, when the owner allows it. 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. 8 credits per image, with or without a character. 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 character photos).
{
"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,
"face_check": { "verdict": "no_drift_found", "score": 91 },
"credits_used": 8
}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 a vision model's reading of how closely the face matches the character's photos, 0–100; it's null when no character was used, the face wasn't checked, or the face check couldn't run.
face_check says the same thing in words, the way Picacho shows it: verdict is no_drift_found (the score is at or above our face line), cant_tell (the score is in the range where the check can't tell whether it is them; judge by eye), drifted (under that range; close-ups hold best), too_small_to_check (no face could be compared), couldnt_run (the check didn't run, so nothing about the face is known) or not_checked (no face check on this take), and score repeats match_score. Both fields stay; read whichever suits you.
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, match_score and face_check 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": 10100,
"used_this_period": 420,
"remaining_this_period": 9680,
"bonus_credits": 0,
"purchased_credits": 0,
"period_started_at": "2026-08-09T00:00:00.000Z",
"plan_credits_start_at": null
}Three balances, drawn in order: remaining_this_period is what's left of the credits included with the plan this month, then bonus_credits, then purchased_credits, a one-off balance (credit packs) that never resets. Generating stops with a 402 only once all three are used, so the real headroom before a batch is their sum. plan_credits_start_at is set only in the month an account moved to the new credit: the plan's credits start on that date.
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" }
}
}
}Seven tools: list_characters, generate_image, get_generation, list_generations, get_usage, list_video_models and prepare_render. Only generate_image spends credits, and it's marked that way so a client asks you first. Videos are made on Picacho itself: prepare_render returns a link that opens the composer with the video set up and its price, and you press Send there.
The reason it's worth connecting rather than calling a generic image API: generate_image comes back with match_score — a reading of how closely the rendered face matches your character's own photos — and face_check, the same reading in words. The assistant shows you the face check with the picture, so you can judge the face yourself; making another one is your call, never the assistant's own.
Connect Claude or ChatGPT (no key)
On a paid plan you can connect by signing in to Picacho instead of using a key. The address is https://picacho.ai/api/mcp; Settings → Security → Connected apps shows it with a Copy button, and every connected app with a Disconnect key.
- Claude: Customize → Connectors → + Add → Add custom connector. Paste the address, press Continue, sign in to Picacho and allow.
- ChatGPT (on the web, Plus or above): turn on Developer mode in Settings → Security and login, then in Plugins press + and create an app with the address. Sign in to Picacho when it asks.
Then ask in plain words, for example: “What characters do I have on Picacho?”, “Make a picture of Eva reading in a sunlit café”, “Set up a 5-second video of Eva walking on the beach at dusk — what will it cost?”, or “Show me my last three renders and their face scores.” A picture is made right there for 1 credit; a video comes back as a link that opens Picacho set up, and you press Send there.