TokenLab Expands GPT Image Edit API Support

TokenLab has expanded its image edit API to support the latest GPT Image edit workflows, including multi-image inputs and async task polling for gpt-image-2. If you are building edit features on top of GPT Image models, the edit endpoint now handles both multipart uploads and JSON image references, with async mode available for larger or slower jobs.

Key Takeaways

What Changed

Image editing has become one of the more demanding parts of any AI product surface. Users want to upload a photo, describe a change, and get a result back quickly, but edit requests involving multiple reference images or higher-resolution outputs take longer than a typical synchronous HTTP call comfortably allows. That gap has been the main friction point for teams building on GPT Image models through TokenLab.

The update addresses this directly. The /images/edit endpoint now recognizes when a request is going to gpt-image-2 and offers two paths: a standard synchronous call for simple, single-image edits, and an async mode for anything more involved. Requests with multiple source images, larger canvases, or heavier prompt instructions are natural candidates for async mode, since they take longer to complete and you do not want a client connection sitting open waiting on them.

This is not a breaking change. If your integration already calls the edit endpoint synchronously, it keeps working. The async path is opt-in, triggered by a request parameter, and the response shape for sync calls is unchanged.

Multipart Uploads vs JSON Image References

One practical improvement worth calling out: the edit endpoint accepts images two different ways, and you can pick whichever fits your stack better.

Multipart form uploads. If your application already has image bytes in hand, whether from a user upload or a generated asset, you can send them directly as multipart form data. This is the simpler path for server-side code that is proxying a file straight from a client upload.

JSON image references. If your images already live somewhere accessible by URL, or you generated them earlier in a TokenLab request and have a reference to reuse, you can pass that reference in the JSON body instead. This avoids re-uploading bytes you already have and is generally the better choice for pipelines that chain generation and editing steps.

Both approaches work with GPT Image edit requests. Which one to use is a matter of what shape your data is already in, not a functional tradeoff. If you are building a pipeline that generates an image, checks it, and then edits it, the JSON reference path usually saves a redundant upload step.

Multi-Image Edits with gpt-image-2

The bigger functional addition is multi-image support for gpt-image-2. Instead of editing a single source image, you can now pass multiple images in one edit request and let the model use them together, for example combining a subject photo with a reference background, or applying a style transfer using a second image as guidance.

Because multi-image edits do more work per request, they are also the clearest case for using async mode. Sending several images and a complex instruction set through a synchronous call means holding a connection open for however long the model needs, which is a poor fit for most client timeouts and load balancer configurations. Async mode sidesteps this: you submit the request, get back a task reference immediately, and poll for the result on your own schedule.

Async Mode: When and How to Use It

Async mode works the same way across the parts of the TokenLab API that support it. You submit your edit request with the async flag set, and instead of waiting for the final image, you get a task identifier back right away. From there, you poll a status endpoint until the task reports as complete, at which point the response includes your result.

Use async mode when:

• You are sending multiple source images in a single edit request.
• Your prompt or instructions are complex enough that generation time is unpredictable.
• You are running edits in a background job, queue, or batch process rather than a live user-facing request.
• You want to decouple your client's request lifecycle from the model's actual processing time.

Stick with synchronous mode when:

• You are doing a simple, single-image edit with a short prompt.
• Your application already has short timeout budgets and prefers to fail fast rather than poll.

Integration Checklist

Before you switch a workflow to gpt-image-2 edits, run through this:

• Confirm you are targeting the /images/edit endpoint and specifying the correct model.
• Decide whether your images are better sent as multipart uploads or JSON references, based on where they currently live in your pipeline.
• If your edit involves more than one source image, enable async mode rather than assuming a synchronous response.
• Implement a polling loop with reasonable backoff for async tasks rather than tight polling.
• Handle the task-pending state explicitly in your client code, distinct from a final error or success state.
• Test with your largest expected image count and prompt length before shipping to production.

Example Request

curl -X POST https://api.tokenlab.sh/v1/images/edit \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "images": ["ref://your-image-reference-1", "ref://your-image-reference-2"],
    "prompt": "combine these into a single edited scene",
    "async": true
  }'

Adjust the reference values and prompt to match your actual pipeline. For multipart uploads, replace the JSON image references with a standard multipart form body instead.

FAQ

Does async mode change the output quality or format of gpt-image-2 edits? No. Async mode only changes how you retrieve the result. The model processes the request the same way; you are simply polling for the finished image instead of waiting on an open connection.

Can I mix multipart uploads and JSON image references in the same request? The endpoint is built to accept one input style per request. Pick whichever matches where your image data currently lives, and convert if you need to combine sources from both formats.

Do I need to change existing single-image edit integrations? No. Single-image, synchronous edit calls continue to function exactly as before. Async mode and multi-image support are additive capabilities you opt into when you need them.

Sources and Freshness

This update reflects TokenLab API behavior observed as of 2026-07-07. For the current endpoint reference, see the image edit API documentation and the image generation guide. For broader model comparisons, see Best AI Image Models API 2026.

Get Started

If you are building image editing features and want a single API surface across GPT Image, Nano Banana Pro, and other image models, TokenLab gives you one integration point with support for both sync and async workflows. Check the docs and get an API key to start testing gpt-image-2 edits today.

Related Reading and Next Step

If you're deciding how GPT Image Edit fits into your broader image pipeline, a few resources can help. Start with the Best AI Image Models API Guide: How to Choose Image Generation and Editing Models for a comparison of leading providers and their editing capabilities. If you're weighing OpenAI's offering against Google's, GPT Image API vs Gemini Image API: How to Choose breaks down strengths, pricing structures, and use cases for each. And if you want a fast, low-cost editing option alongside GPT Image, the Nano Banana API Guide: Image Generation and Editing Through TokenLab covers setup and practical examples.

Model availability, rate limits, and pricing can change, so confirm current details before scaling any workflow into high-volume production.

Ready to start building? Create an API key and test GPT Image Edit alongside other supported models in minutes.