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://…"}, …]}

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