API reference

The one endpoint here that needs no API key, because an agent arriving with no account has nothing to authenticate with. It creates an account, emails a claim link to the address you supply, and returns a live key you can use immediately.

**Only use an address the person you are acting for can actually read.** The account is theirs, not yours: the emailed link signs them in, and an account nobody claims is deleted automatically along with the key.

An address that already has an account gets 202 and **no key**. That is deliberate and is not an error you can work around: issuing a key for an existing address would be account takeover by email address. Sign in and create one from the account page instead.

Rate limited per address and capped per day across the whole service, and it can be switched off entirely, in which case it answers 403 signup_disabled. If you need a key without this, the Device Authorization Grant is the supported path and has no such limits.

Read-only and unmetered: asking how much allowance you have never spends any of it. This is the call to make first to check a key works.

A test key sees the account's real balance and real usage, with mode saying which world it is in. Hiding them would make the endpoint useless for checking an integration.

Built-in presets are shared by every account and cannot be edited. Your own are the ones saved through this endpoint or in the web app: an API key and a signed-in browser session on the same account see the same list.

Send only the fields you care about. The stored preset is your config layered over the defaults, so reading it back gives a complete config rather than a fragment whose meaning depends on which build answered.

Synchronous. Send base64 image bytes or a public https URL, and get a signed URL to the result. Exactly one of image_base64 and image_url is required; sending both is a 400 rather than a silent choice between them.

image_url is fetched server side, on port 443 only, with redirects refused and the connection pinned to an address that has already been checked, so a URL resolving to a private or link-local address is refused. Every fetch failure returns the same message on purpose: an answer that told a closed port from an open one would be a port scanner.

The URL is valid for 60 seconds, so fetch it as part of handling the response rather than storing it. Sending Idempotency-Key makes a retry safe: for 24 hours the same key returns the same result with a freshly signed URL, and the same key with a different body is 422 rather than a silent second charge.

Configuration is layered: defaults, then preset_id, then config. So preset_id plus config: {"quality": 90} means "that preset, at 90".

RFC 8628 section 3.1. Unauthenticated, because having no credential yet is the point. Show the returned user_code to your human alongside verification_uri, then poll /v1/token.

verification_uri_complete is a convenience link with the code already in it. Show the code as well even when you use it: the human is asked to compare what is on their screen with what is on yours, and that comparison is what stops a stranger from talking somebody into approving a code they were sent.

Send the body as application/x-www-form-urlencoded. JSON is accepted too.

RFC 8628 section 3.4. Poll no faster than the interval you were given.

**While you wait, this returns HTTP 400 with error: authorization_pending.** That is what RFC 6749 section 5.2 specifies for these errors and it does not mean anything is wrong. Only authorization_pending and slow_down mean keep polling; every other error code is terminal and you should stop.

On slow_down, add five seconds to your interval permanently. On a connection failure or a 503, back off exponentially instead: that is a different rule and the two are easy to confuse.

The key you receive does not expire and is revoked by its owner at /account. It arrives in exactly one HTTP response and cannot be retrieved again, so store it before you do anything else.