curl --request POST \
--url https://api.poyo.ai/api/generate/submit \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "ideogram-v4.6-edit",
"callback_url": "https://your-domain.com/callback",
"input": {
"prompt": "Replace the background with a blue photo studio",
"image_urls": [
"https://example.com/source.png"
]
}
}
'{
"code": 200,
"data": {
"task_id": "task-unified-1757165031-uyujaw3d",
"status": "not_started",
"created_time": "2026-10-13T10:30:00+08:00"
}
}{
"code": 400,
"error": {
"message": "Invalid request parameters",
"type": "invalid_request_error"
}
}{
"code": 400,
"error": {
"message": "Invalid request parameters",
"type": "invalid_request_error"
}
}Ideogram
Ideogram V4.6 Edit
The Ideogram 4.6 Edit API edits one source image from a text prompt, with an optional mask, up to four reference images, regular or high-precision editing, and localized edits that keep the original resolution.
POST
/
api
/
generate
/
submit
curl --request POST \
--url https://api.poyo.ai/api/generate/submit \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "ideogram-v4.6-edit",
"callback_url": "https://your-domain.com/callback",
"input": {
"prompt": "Replace the background with a blue photo studio",
"image_urls": [
"https://example.com/source.png"
]
}
}
'{
"code": 200,
"data": {
"task_id": "task-unified-1757165031-uyujaw3d",
"status": "not_started",
"created_time": "2026-10-13T10:30:00+08:00"
}
}{
"code": 400,
"error": {
"message": "Invalid request parameters",
"type": "invalid_request_error"
}
}{
"code": 400,
"error": {
"message": "Invalid request parameters",
"type": "invalid_request_error"
}
}- After submission, a
task_idwill be returned. If you provided acallback_url, when the task status becomesfinishedorfailed, a POST request will be sent to thecallback_url. - Regardless of whether
callback_urlis provided, you can retrieve the response result through the unified Query Task Status endpoint.
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: highmakes 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
| Mode | Settings | What happens |
|---|---|---|
| Regular edit (default) | edit_precision: regular | The image is regenerated from the prompt. Without a mask, size can change the output size. background is supported. |
| High-precision edit | edit_precision: high, context_window: none | The whole image is edited precisely and unchanged pixels are restored. The output keeps the original resolution. |
| Localized edit | edit_precision: high, context_window: auto, mask_url | Only the region around the mask is edited. The original resolution and every pixel outside that region are kept. A mask that is too large falls back to whole-image editing. |
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. Requiressizeto beauto.reference_image_urls(array of strings): 0 to 4 reference images, or at most 3 whenmask_urlis set. Public HTTP(S) URLs or base64 image data URIs.edit_precision(string):regularorhigh. Default isregular.regularregenerates the image;highis a precise edit that restores unchanged pixels.highrequiressizeto beauto.context_window(string):noneorauto. Default isnone.autorequiresedit_precision: highandmask_url. See Edit modes.size(string):auto,1:1,1:1 HD,4:3,3:4,16:9,9:16, or a customWIDTHxHEIGHT. Default isauto, which keeps the source geometry. See Size.quality(string):very_low,low,medium, orhigh. Default ismedium.very_lowis limited to outputs of at most 4,194,304 pixels.background(string):transparentoropaque. Regular edits only; rejected whenedit_precisionishigh.n(integer): Number of results,1to8. Default is1.seed(integer): Random seed,0to2147483647. 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 insideinput.
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 withmask_urloredit_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), and9:16(576×1024). - Custom
WIDTHxHEIGHTsizes use a lowercasex. Both sides must be from256to4096pixels and multiples of32, and the aspect ratio must be within1:6and6:1.
Output
When an Ideogram 4.6 Edit API task isfinished, 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 toPOST /api/generate/submit with your API key in the Authorization header.
Edit Image
{
"model": "ideogram-v4.6-edit",
"callback_url": "https://your-domain.com/callback",
"input": {
"prompt": "Replace the background with a blue photo studio",
"image_urls": [
"https://example.com/source.png"
]
}
}
Localized Masked Edit
{
"model": "ideogram-v4.6-edit",
"input": {
"prompt": "Change the sign text to \"OPEN LATE\"",
"image_urls": [
"https://example.com/storefront.png"
],
"mask_url": "https://example.com/sign-mask.png",
"edit_precision": "high",
"context_window": "auto",
"quality": "high"
}
}
Restyle With A Reference Image
{
"model": "ideogram-v4.6-edit",
"input": {
"prompt": "Restyle the product shot to match the reference",
"image_urls": [
"https://example.com/product.png"
],
"reference_image_urls": [
"https://example.com/style.png"
],
"size": "2048x2048",
"quality": "low",
"n": 2
}
}
Notes
- The Ideogram 4.6 Edit API requires exactly one source image in
image_urls. context_window: autowithoutedit_precision: highandmask_urlis rejected.very_lowwith 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
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:
Authorization: Bearer YOUR_API_KEY
Body
application/json
Response
Task submitted successfully
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: Success400: Invalid request parameters401: Missing or invalid API key402: Insufficient credits403: Permission denied404: Resource not found408: Request timeout429: Rate limit exceeded500: Internal server error502: Upstream service error503: Service unavailable
See Error Codes for details.
Available options:
200, 400, 401, 402, 403, 404, 408, 429, 500, 502, 503 Example:
200