Image Editing
Edit images, inpaint with masks, and create variations with the Images API.
Overview
The Images API edits an existing image in three ways: whole-image edits, mask-based inpainting, and variations. Every mode takes its source image (and optional mask) as an uploaded asset — there is no URL or inline path.
Warning
/v1/images/edits and /v1/images/variations accept application/json only. The legacy multipart/form-data file upload was removed — sending multipart returns 415 legacy_multipart_removed. Whether the image is a few KB or 25 MB, the source and mask must first go through presigned upload, then you submit JSON with image_upload_id / mask_upload_id.
Three modes
| Mode | Endpoint | Required | Effect |
|---|---|---|---|
| Whole-image edit | POST /v1/images/edits | model, prompt, image_upload_id | Edit the whole image per the prompt |
| Mask inpaint | POST /v1/images/edits | the above + mask_upload_id | Change only the masked region |
| Variation | POST /v1/images/variations | model, image_upload_id (no prompt) | Generate same-style variants |
Passing mask_upload_id automatically switches an edit into inpainting — no extra flag needed.
Editing an image
First presign and upload the source with purpose=image_edit_source (and, for inpainting, the mask with purpose=image_edit_mask). Then submit JSON:
| 1 | curl https://api.alltoken.ai/v1/images/edits -H "Authorization: Bearer $ALLTOKEN_API_KEY" -H "Content-Type: application/json" -d '{ |
| 2 | "model": "gpt-image-1.5", |
| 3 | "prompt": "Change the background to a sunset", |
| 4 | "image_upload_id": "upl_source...", |
| 5 | "mask_upload_id": "upl_mask...", |
| 6 | "size": "1024x1024", |
| 7 | "output_format": "png" |
| 8 | }' |
Common optional fields: size, quality, output_format, output_compression, background, moderation, n, user. See the Image API reference for the full list.
Creating variations
Variations need only a source (uploaded with purpose=image_variation_source) — no prompt:
| 1 | curl https://api.alltoken.ai/v1/images/variations -H "Authorization: Bearer $ALLTOKEN_API_KEY" -H "Content-Type: application/json" -d '{ |
| 2 | "model": "gpt-image-1.5", |
| 3 | "image_upload_id": "upl_source...", |
| 4 | "n": 2 |
| 5 | }' |
Optional fields: size, n, output_compression, user.
Getting the result
Creation returns 202 + { id, status: "queued", ... }. All three modes poll the same endpoint:
$curl https://api.alltoken.ai/v1/images/generations/{id} -H "Authorization: Bearer $ALLTOKEN_API_KEY"While queued / processing, the response carries next_poll_after_ms — use it to pace the next poll. When completed, each data[] item has b64_json, r2_url, r2_url_expires_at, mime_type, and revised_prompt.
Warning
b64_json is delivered once — only the first completed GET returns it, so write it to disk immediately. Prefer r2_url (valid 30 days, cross-device) and treat b64_json as the first-fetch fallback. After r2_url expires the GET returns 410 image_expired. There is no "list images" endpoint — record results by task_id yourself.
Batch editing
One request handles one source image (plus one optional mask). To edit N images, run N independent three-step flows — each with its own presign → PUT → create → poll. You can run them concurrently; mind two limits:
- 100 pending uploads — don't presign hundreds of
upload_ids and leave them unused. - 2 GiB per UTC day — roughly 80 files of 25 MiB reaches the cap.
Recommended: keep 5–10 concurrent lanes, each running a full presign → PUT → create → poll before taking the next image. The pending count stays small and you never hit the quota. See Media Uploads for the quota details.