Skip to main content
POST
  1. After submission, a task_id will be returned. If you provided a callback_url, when the task status becomes finished or failed, a POST request will be sent to the callback_url.
  2. Regardless of whether callback_url is provided, you can retrieve the response result through the unified Query Task Status endpoint.
The Ideogram 4.6 Edit API is the image-editing model of the Ideogram 4.6 API. Send one source image and a prompt to replace a background, change the text on a sign, restyle a product shot, or repaint only the area you mark with a mask. Reference images guide the style or content, and high-precision editing restores every pixel you did not ask to change. To create images from a prompt alone, use the Ideogram 4.6 API text-to-image model.

Ideogram 4.6 API models

  • ideogram-v4.6-edit — Edit exactly one source image, with an optional mask, reference images, and precision controls
  • ideogram-v4.6 — Text-to-image generation. See Ideogram V4.6

Ideogram 4.6 Edit API features

  • Prompt-based editing: Describe the change in plain language. Put exact on-image text in quotes.
  • Masked edits: Black areas of the mask are edited and white areas are kept.
  • Reference images: Add up to four reference images, or three when a mask is set.
  • High-precision editing: edit_precision: high makes a precise edit and restores unchanged pixels.
  • Localized edits at full resolution: With context_window: auto, the Ideogram 4.6 Edit API edits only the region around the mask and keeps the source resolution.
  • Batches, backgrounds, and seeds: Up to 8 results per request, transparent backgrounds for regular edits, and repeatable seeds.

Edit modes

Required parameters

  • prompt (string): Description of the edit, 1–10,000 characters. Must contain non-whitespace text.
  • image_urls (array of strings): Exactly one source image. Use a public HTTP(S) image URL or a base64 image data URI (data:image/<type>;base64,...). It must be an array, even for one image.

Optional parameters

  • mask_url (string): Mask image with the same dimensions as the source. Black areas are edited and white areas are kept; the mask must contain both. Public HTTP(S) URL or base64 image data URI. Requires size to be auto.
  • reference_image_urls (array of strings): 0 to 4 reference images, or at most 3 when mask_url is set. Public HTTP(S) URLs or base64 image data URIs.
  • edit_precision (string): regular or high. Default is regular. regular regenerates the image; high is a precise edit that restores unchanged pixels. high requires size to be auto.
  • context_window (string): none or auto. Default is none. auto requires edit_precision: high and mask_url. See Edit modes.
  • size (string): auto, 1:1, 1:1 HD, 4:3, 3:4, 16:9, 9:16, or a custom WIDTHxHEIGHT. Default is auto, which keeps the source geometry. See Size.
  • quality (string): very_low, low, medium, or high. Default is medium. very_low is limited to outputs of at most 4,194,304 pixels.
  • background (string): transparent or opaque. Regular edits only; rejected when edit_precision is high.
  • n (integer): Number of results, 1 to 8. Default is 1.
  • seed (integer): Random seed, 0 to 2147483647. Omit it to pick one automatically.
  • callback_url (string): Optional webhook URL for task completion notification. Send it at the top level of the request, not inside input.
The Ideogram 4.6 Edit API accepts only these fields in input. Any other field is rejected with an unsupported fields error.

Size

  • auto (default) keeps the source geometry. For the Ideogram 4.6 Edit API, it is the only value allowed with mask_url or edit_precision: high. Otherwise the request fails with “mask_url or high edit_precision requires size auto”.
  • For regular edits without a mask, you can also use the presets 1:1 (512×512), 1:1 HD (1024×1024), 4:3 (1024×768), 3:4 (768×1024), 16:9 (1024×576), and 9:16 (576×1024).
  • Custom WIDTHxHEIGHT sizes use a lowercase x. Both sides must be from 256 to 4096 pixels and multiples of 32, and the aspect ratio must be within 1:6 and 6:1.

Output

When an Ideogram 4.6 Edit API task is finished, files contains one entry per edited image, each with file_url and file_type: image.

Ideogram 4.6 Edit API examples

Send each Ideogram 4.6 Edit API request below to POST /api/generate/submit with your API key in the Authorization header.

Edit Image

Localized Masked Edit

Only the area around the black part of the mask is edited, and the original resolution is kept.

Restyle With A Reference Image

Notes

  • The Ideogram 4.6 Edit API requires exactly one source image in image_urls.
  • context_window: auto without edit_precision: high and mask_url is rejected.
  • very_low with a custom size above 4,194,304 pixels is rejected.
  • The source image, mask, and reference images can be public HTTP(S) URLs or base64 image data URIs. To use local files, you can also upload them first with File Management.
  • Generated image files are accessible for 3 days after creation. Download and store them promptly.
  • The response returns a task_id. Query the task status to get the edited images.

Authorizations

Authorization
string
header
required

All API endpoints require Bearer Token authentication.

Create an API key: sign in to PoYo, open Dashboard → API Key at poyo.ai/dashboard/api-key, and click to create a key.

Add it to the request header:

Body

application/json
model
enum<string>
required

Ideogram 4.6 Edit model identifier.

Available options:
ideogram-v4.6-edit
input
object
required

Edit exactly one source image.

callback_url
string<uri>

Optional webhook URL for task completion or failure.

Response

Task submitted successfully

code
enum<integer>
required

Business status code. 200 means success; any other value means the request failed. Always check this field: some validation errors return HTTP 200 with code: 400 in the body.

  • 200: Success
  • 400: Invalid request parameters
  • 401: Missing or invalid API key
  • 402: Insufficient credits
  • 403: Permission denied
  • 404: Resource not found
  • 408: Request timeout
  • 429: Rate limit exceeded
  • 500: Internal server error
  • 502: Upstream service error
  • 503: Service unavailable

See Error Codes for details.

Available options:
200,
400,
401,
402,
403,
404,
408,
429,
500,
502,
503
Example:

200

data
object
required