AI Image Editing API Selection Guide: Endpoints, Inputs, and Cost Units

The best AI image editing API is rarely the one with the best demo. It is the one whose endpoint, input shape and billing unit match the edit your product actually performs. Mask edits, reference-guided image-to-image and model-specific edit operations do not share one contract. We read TokenLab's edit docs and live model pages on 2026-10-03, and everything below comes from those pages. Image endpoints choose no default model for you, so always send model explicitly.

Key Takeaways

Starting picks by use case

These picks follow the documented contract and the listed price. They are not quality rankings, because the evidence has no edit-quality benchmark. Treat each as the first model to put in your own test set.

You need	Starting pick	Why	Source
Mask-based inpainting	gpt-image-2	It is the only model whose mask contract is spelled out: PNG, same dimensions, transparent areas are edited.	Edit Image reference, 2026-10-03
Many source images in one edit	gpt-image-2	Documented limit of 16 source images. Grok Imagine edit models cap at 3.	Edit Image reference, 2026-10-03
Cheapest flat-price reference edit	grok-imagine-image	$0.02 per request, the lowest flat price in our table.	live model API, 2026-10-03
Keep product shape, change the scene	nano-banana-pro	The documented reference example does exactly this, at $0.067 per image.	Create Image reference, 2026-10-03
Text inside edited images	No pick	The evidence has no text-rendering data for any edit model.	n/a

Best AI image editing API candidates: models, units and prices

The table lists every model from our evidence set that is listed as editing-capable or that the edit docs name as an edit model. All prices are TokenLab public prices in USD. The live API reported pricing updated 2026-10-02T16:53:30.068Z, and we observed each page on 2026-10-03.

Model ID	Capabilities listed on live API	Pricing unit	TokenLab price (USD)	Source	Observed
gpt-image-2	text-to-image (edit documented on /v1/images/edits)	per_token	$3.50/1M text input, $5.60/1M image input, $21/1M image output; cached text input $0.875/1M	live model API	2026-10-03
flux-kontext-pro	image-edit, image-to-image, text-to-image	per_request	$0.04	live model API	2026-10-03
flux-pro-1.0-fill	image-to-image	per_image	$0.035	live model API	2026-10-03
flux-2-pro	image-to-image, text-to-image	per_image	$0.03	live model API	2026-10-03
nano-banana-pro	image-edit, image-to-image, text-to-image	per_image	$0.067 (price range summary up to $0.12)	live model API	2026-10-03
gemini-3-pro-image	image-to-image, text-to-image, vision	per_token	$1/1M input, $6/1M text output, $60/1M image output	live model API	2026-10-03
gemini-3.1-flash-image	image-to-image, text-to-image, vision	per_token	$0.25/1M input, $1.50/1M text output, $30/1M image output	live model API	2026-10-03
grok-imagine-image	image-to-image, text-to-image	per_request	$0.02	live model API	2026-10-03

When we lined the pages up, we found three mismatches. The live API lists gpt-image-2 as text-to-image only, yet the Edit Image reference says it is supported on /v1/images/edits. The live pages for flux-pro-1.0-fill and flux-2-pro list image-to-image, while our catalog snapshot labels both as image-edit. And nano-banana-pro lists image-edit, but its docs route it through /v1/images/generations. We treat the docs as authoritative for routing and the live API as authoritative for price.

For the flat-priced models, a rough estimate is simple multiplication. These are estimates, not quotes, and they assume one charge per completed request:

• 100 edits on grok-imagine-image: 100 × $0.02 = $2.00.
• 100 edits on flux-2-pro: 100 × $0.03 = $3.00.
• 100 edits on flux-pro-1.0-fill: 100 × $0.035 = $3.50.
• 100 edits on flux-kontext-pro: 100 × $0.04 = $4.00.

The evidence gives no per-edit estimate for the token-priced models. gpt-image-2 bills text input, image input, reported cached input and image output tokens, so it is not a fixed per-image model. The evidence includes no token counts for a typical edit. Run a few real edits and read the cost in Usage, as the Billing guide describes. The nano-banana-pro price range implies resolution tiers, but the evidence does not map tiers to prices.

What the edit endpoint accepts, and what it does not document

The Edit Image reference (observed 2026-10-03) supports an OpenAI-compatible multipart flow and JSON requests. Here is what it states for gpt-image-2:

• Input image. Send multipart image, JSON image_url / image_urls, or official images[] objects. Each images[] object holds exactly one of image_url or file_id. Create file_id values through /v1/files first.
• Multiple references. Up to 16 source images, each PNG, JPEG or WebP, up to 50 MiB. Repeat the image field in multipart requests. In JSON, provide exactly one of image_url, image_urls or images.
• Mask. A PNG under 50 MiB with the same dimensions as the source image. Fully transparent areas mark where the edit applies. In JSON, mask may be an object with exactly one of image_url or file_id.
• Output. size accepts auto or WIDTHxHEIGHT. Dimensions must be multiples of 16, the longest edge at most 3840px, the long-to-short ratio at most 3:1, and total pixels between 655,360 and 8,294,400. Do not send resolution. background accepts auto or opaque, not transparent.
• Rejected field. input_fidelity is not supported for gpt-image-2, and sending it returns 400 unsupported_parameter.
• Remote URLs. They must be public http/https, with no embedded credentials or fragments. They must not resolve to localhost, private or reserved ranges. Limits are 50 MiB per image, 200 MiB total per request (including the mask), a 30s fetch timeout and up to 3 redirects. The fetched payload must be a real PNG, JPEG or WebP.

Grok Imagine edit models (grok-imagine-image, grok-imagine-image-quality) use the same input fields but cap source images at 3. A request with more fails with 400 too_many_images.

Nano Banana is different. The docs say nano-banana-2 and nano-banana-pro take reference-image requests on /v1/images/generations with operation: "image-to-image" and image_urls. They do not belong on /v1/images/edits. Top-level images[] and file_id are edit-flow shapes and are rejected on the generations endpoint. Here is a documented example for nano-banana-pro, which accepts resolution:

{
  "model": "nano-banana-pro",
  "prompt": "Keep the product shape, change the background to a bright studio setup",
  "operation": "image-to-image",
  "image_urls": ["https://example.com/input/product.png"],
  "aspect_ratio": "1:1",
  "resolution": "2k"
}

For Google image families, the Create Image reference says to prefer aspect_ratio and send resolution (1k, 2k, 4k) only where the model supports it. Model details for nano-banana-2 are linked here, but the evidence set does not include its price.

Not documented in the evidence:

• Whether models other than gpt-image-2 accept mask on /v1/images/edits, including flux-pro-1.0-fill and stability-inpaint.
• How a single mask applies when you send several source images.
• Source-image limits for the FLUX and Nano Banana models.
• Whether image order in a multi-image request affects the result.

Read the model's detail page before building on any of these.

One complete edit request

This request uses only documented fields for gpt-image-2: a source image, a mask, a prompt, size and async. It follows the multipart example in the Edit Image reference.

curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -F "model=gpt-image-2" \
  -F "image=@source.png" \
  -F "mask=@mask.png" \
  -F "prompt=A sunlit indoor lounge area with a pool" \
  -F "n=1" \
  -F "size=1024x1024" \
  -F "async=true"

With async=true, the response carries status: "pending", task_id and poll_url, and data stays empty. Drop the async line for a synchronous call. A synchronous call returns data[].url by default, or data[].b64_json if you set response_format. Poll the task like this:

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $TOKENLAB_API_KEY"

Model details for gpt-image-2 are on its model page. For a synchronous call, set your HTTP client timeout to at least 120s, because high-resolution requests can take close to a minute or longer.

Choosing the best AI image editing API by task

The evidence states routing, inputs and prices. It contains no benchmark of edit quality, so every "which is better" question below needs your own test set.

Inpainting. gpt-image-2 is the only model whose mask contract the docs spell out. The catalog also lists dedicated region and structure tools: stability-inpaint, stability-control-structure and stability-control-sketch. For fill and in-context edits, there are flux-pro-1.0-fill at $0.035 per image and flux-kontext-pro at $0.04 per request. The evidence does not say which produces cleaner seams.

Style-preserving edits. The documented reference example keeps a product's shape and changes the surroundings. That is the nano-banana-pro pattern on /v1/images/generations. flux-kontext-pro lists image-edit capability. Neither claim is benchmarked here for identity or style retention.

Text in images. The evidence contains no information on text rendering for any edit model. ideogram-edit-v3 and ideogram-reframe-v3 exist in the catalog, but we found no text-quality data. Test with your own copy, fonts and languages.

Product shots. Imagine a catalog team that swaps backgrounds on thousands of packshots. The utility tools are the natural first look: image-background-remover, image-upscaler and stability-upscale-fast. Their pricing and input rules are not in our evidence, so read each model page. For generative background swaps, flat per-request pricing makes batch costs easy to forecast. Token pricing makes them depend on image size and output.

Input requirements are per model, not per provider. Some models take one source image plus a prompt, some take a mask, and some take structural inputs. Check each model's supported operations and request fields on its detail page. You can browse the current options in the model directory.

Async handling and cost confirmation for edits

The Image generation guide and the Async jobs guide (both observed 2026-10-03) describe the flow. async: true is documented for gpt-image-2 and official FLUX/BFL edit models. The create response returns status: "pending", task_id and poll_url. Poll poll_url when present, or GET /v1/tasks/{id} for a fixed URL. Statuses are pending, processing, completed and failed. The docs suggest checking every 5–10 seconds for long media jobs and stopping at a terminal status.

Four details cause most bugs:

• A status read returns HTTP 200 even when the task failed. Branch on status, and on error_details.code and type for failures.
• Completed async edits return URLs regardless of response_format. Use a synchronous request when you need b64_json.
• After a client timeout, check whether a task exists before you retry the create call. Retrying a failed generation creates a new task and may create a new charge.
• Result URLs may be kept as media copies for 30 days. Check media_retention.items for each item's status and expires_at.

For cost, the Billing guide says Console shows the maximum estimate before you confirm a paid generation, and Usage shows the final charge. An async task may reserve its estimated cost when accepted. A completed task is charged once, and a failed or timed-out task releases or refunds the pending amount. Delivery options matter too. TokenLab Verified uses TokenLab public prices, Official uses the Official price layer, and Auto tries Verified first, then Official. A dash in the Models page price column means no Verified offer is available, not that the model is free. A spending limit on an API key returns 402 Payment Required once reached.

Store request_id, task_id, poll_url, billing_transaction_id (when present), the model, the endpoint and your own job ID together. In practice that record settles most billing-mismatch questions. The evidence documents task cancellation only for queued Seedance video tasks. Cancellation for image edits is not documented, so design your flow without it.

FAQ

Can I send a mask to every image edit model?

The evidence only documents masks for gpt-image-2 on /v1/images/edits. The mask must be a PNG under 50 MiB with the same dimensions as the source, and transparent areas are edited. For other models, including flux-pro-1.0-fill, check the model detail page before you assume mask support.

Which endpoint do Nano Banana edits use?

Use POST /v1/images/generations with operation: "image-to-image" and image_urls. Sending Nano Banana reference requests to /v1/images/edits is not supported. Do not send top-level images[] or file_id to the generations endpoint either.

Why does my gpt-image-2 edit return 400 unsupported_parameter?

The most documented cause is input_fidelity, which is not a supported field for gpt-image-2. Also remove resolution and any background: "transparent" value. The common-errors table advises removing any field the model does not document.

Am I charged when an async edit task fails?

The billing guide says a failed task is not charged, and its reserved amount is released or refunded. A completed task is charged once, and the final amount appears in Usage with a billing_transaction_id. If Usage still shows nothing after the task ends, contact support@tokenlab.sh with the request ID and task ID.

To run the requests above, create an API key under Console → API Keys (key limits are explained in the Billing guide), export it as TOKENLAB_API_KEY, and compare your sample edits against the final cost in Usage.