Edit Image

OverviewCopy Anchor Link

Creates an edited or extended image given an original image and a prompt.

This endpoint supports both:

• the OpenAI-compatible multipart/form-data upload flow documented below
• JSON requests that provide image_url, image_urls, or official images references for supported image-to-image families

Request BodyCopy Anchor Link

Synchronous request timeout: Some image requests return the final image inline and wait for generation to finish. High-resolution or high-quality requests can take close to a minute or longer, so set your HTTP client timeout to at least 120s. If the create response includes status: "pending", task_id, or poll_url, follow the returned poll_url instead.

Remote image URLs: when multipart input is needed, TokenLab fetches JSON image_url, image_urls, or images[].image_url and sends the bytes as multipart image parts. URLs must be public http/https, without embedded credentials or fragments, and must not resolve to localhost, private, or reserved IP ranges; each redirect is checked again. The fetched payload must be a real PNG, JPEG, or WebP image. Limits are 50 MiB per image, 200 MiB total for URL-fetched images in one request, 30s fetch timeout, and up to 3 redirects.

For JSON requests, provide exactly one of image_url, image_urls, or images. Each images[] object must contain exactly one of image_url or file_id. The 200 MiB aggregate limit includes all source images and the mask.

ResponseCopy Anchor Link

Async Task ResponseCopy Anchor Link

Set async: true with gpt-image-2 or official FLUX/BFL edit models to create a task instead of waiting for the edited image in the request. The response includes status: "pending", task_id, and poll_url. Poll /v1/tasks/{task_id} until the task reaches completed or failed.

Async edit tasks return final image URLs only. If you need raw b64_json image data, use a synchronous request.

Billing may reserve the estimated amount when the task is created. Completed tasks are billed by actual usage, and failed or timed-out tasks are released or refunded.

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

{
  "created": 1706000000,
  "data": [
    {
      "url": "https://..."
    }
  ]
}

NotesCopy Anchor Link

{
  "model": "hy-image-v3.5-preview",
  "prompt": "Change the table to pale blue",
  "image_url": "https://example.com/reference.png",
  "size": "1024x1024",
  "n": 1,
  "response_format": "url"
}