Hermosso API

Every studio tool over REST — image generation, editing, upscaling to 22K, photo-to-video. Authenticated with a key, billed from the credits your plan already includes.

Getting a key

API access is included with the Studio plan. Create a key under Billing → API keys. The key is shown once and never again — we store only a hash, so it cannot be recovered. If you lose one, revoke it and make another.

Authentication

curl https://hermosso.com/api/v1/me \
  -H "Authorization: Bearer pm_live_…"

Entitlement is checked on every request rather than at key creation, so a subscription change takes effect immediately — and a plan set to cancel keeps working until the period it was paid for ends.

Billing

Requests draw on your plan's credits. There is no separate meter and no second invoice: a call costs exactly what the same action costs inside the app, because it runs the same code. credits_remaining comes back on every response so you can track spend without a second request.

Failed work is refunded automatically — when the provider reports a failure, and after thirty minutes for a job that never reports at all.

Endpoints

A complete run

Generation is asynchronous — a request returns job ids straight away, and you poll until they finish.

# 1. start the work
curl -X POST https://hermosso.com/api/v1/images/generate \
  -H "Authorization: Bearer pm_live_…" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A bright calm living room, oak floors, soft afternoon light",
       "model":"nano-banana-2","aspectRatio":"3:4","resolution":"2k","count":2}'

# → 202
# {"jobs":[{"id":70,"kind":"image","status":"pending"},
#          {"id":71,"kind":"image","status":"pending"}],
#  "credits_remaining":59700}

# 2. poll until done
curl "https://hermosso.com/api/v1/jobs?image=70,71" \
  -H "Authorization: Bearer pm_live_…"

# → {"jobs":[{"id":70,"kind":"image","status":"done","url":"https://…"}, …]}

MCP server (AI assistants)

The same tools are available over the Model Context Protocol, so an assistant like ChatGPT or Claude can generate and fetch work directly. Add https://hermosso.com/mcp as an MCP server (streamable HTTP) and send the same key on every request:

POST https://hermosso.com/mcp
Authorization: Bearer pm_live_…

Same key, same Studio plan gate, same credits — an assistant run costs exactly what the app or REST API charges. Five tools:

• list_photoshoot_packs — the curated photoshoot packs (id, name, collection).
• generate_photo — prompt-based text-to-image across every engine, or pack-based photos of the user via their AI Persona.
• photo_to_video — animate a still into a clip on 18 engines.
• motion_transfer — the person from a photo performs a reference clip's movement.
• list_creations — recent photos/videos with URLs; also how you poll a pending job.

Generation is asynchronous here too: tools return job ids and list_creations reports each job done with its url. Persona training stays in the app (10–20 selfies, once); every tool then works on the trained persona.

Set it up in Claude (custom connector)

Any MCP client can connect with the URL and key above. In Claude specifically:

1. Create an API key in Hermosso → Billing → API keys (Studio plan). Give it a name you'll recognize, like the client you'll use it in — keys are revocable individually.
2. In Claude, go to Settings → Connectors → Add custom connector and enter https://hermosso.com/mcp.
3. For authentication choose "No sign-in" — the server uses an API key, not OAuth.
4. Under Request headers, add Authorization with the value Bearer pm_live_… (your key from step 1).
5. Save, then try it: "List my Hermosso photoshoot packs" should return the pack catalog.

From then on you can ask in conversation — "generate a headshot of me from the Executive Studio pack", "animate this photo", "put me in this clip" — and Claude calls the tools, spending your plan's credits at the same rates as the app. Other MCP clients (ChatGPT, Cursor, any streamable-HTTP client) connect the same way: the URL plus the Authorization: Bearer header.

Limits

• Five concurrent generations per account. A sixth returns 429 too_many_concurrent. Reading is never limited, so you can always poll to find out when a slot frees.
• Fifty job ids per /jobs call, per kind.
• Ten active keys per account. Revoke one to make another.

Errors

Every failure returns the same envelope, so you can branch on code rather than parsing prose:

{ "error": { "code": "plan_required", "message": "…" } }

Frequently asked