Limits and rules
Two rules
Results live two hours
A batch and every file in it is deleted about two hours after it finishes (a draft that is never started, two hours after its last change). Download what you need before then. Deleting sooner is fine (DELETE /v1/jobs/{id}). There is no way to keep results longer, on purpose: the API is a processor, not storage.
Server to server only
The key spends your credits, so it never belongs in a browser or a mobile app. The API sends no CORS headers; call it from your backend and hand files to your users from there.
Sizes and formats
| What | Limit |
|---|---|
| Photos per batch | 200 (every plan). Extra photos are listed in rejected. |
| One photo | 25 MB. JPEG, PNG, WebP. Larger sides are worked at up to 4096 px. |
| A ZIP | 100 MB, 300 entries, 1 GB uncompressed; images inside are extracted, everything else ignored. |
| A background image | 25 MB, JPEG, PNG or WebP. |
| A link | http(s), public host, 25 MB (100 MB for zipUrl), 30 s to download. |
| Not accepted | HEIC/HEIF, TIFF, AVIF, GIF, BMP, PDF. Convert to JPEG or PNG first (the studio does this in the browser; the API does not). |
| Output | PNG, JPEG or WebP; canvas up to 8000 × 8000 with custom; upscale ×2 and ×4. |
Rates
| What | Limit | Scope |
|---|---|---|
| Requests | 60 per minute | per key |
| Photos added (files or links) | 2,000 per hour | per key |
| Batches running at once | 2 | per account (a single-image call counts as one) |
| Active keys | 10 | per account |
| Reports per photo | 2 | |
| `wait` on a batch | 60 s per request | |
| An event stream | 10 minutes, then reconnect | |
| A webhook delivery | 10 s to answer, 5 attempts |
Over a rate limit you get 429 RATE_LIMITED with Retry-After. The photo budget is counted when photos are added, not when they run: a rejected photo still counts.
Throughput
Photos in a batch run a few at a time; a 200-photo batch takes minutes, not seconds. estimate.remainingMs in every batch answer is our best guess and gets more accurate as photos finish. Need more? Tell us what you are building through the reference page.
Other things to know
- All timestamps are server time in milliseconds since the epoch (the ledger uses ISO strings).
- Every link in an answer is a path; prefix it with the host and send the key. Links are stable for the life of the batch;
?v=changes when a photo is re-rendered. - Output files carry no metadata: EXIF is applied (orientation) and then stripped.
- Photos are processed and then deleted; nothing is used to train anything.
- The API is versioned in the path. Breaking changes would be a
/v2; additions to/v1(new fields, new endpoints) are not announced ahead of time, so ignore fields you do not know.
Something in this table is in your way? It is a limit, not a law. Write to us with what you are building and the volume; several of these can move.
Next: Recipes. A folder, a shop backend, a webhook flow.