
This Ideogram 4.6 API guide takes you from an API key to a finished image in cURL and Python, then covers every input mode the PoYo schema accepts: text-to-image at preset or custom sizes, transparent backgrounds, regular edits, masked edits, reference images and high-precision edits. Text-to-image uses the model ID ideogram-v4.6 and editing uses ideogram-v4.6-edit; both are listed on the Ideogram 4.6 model page.
Field rules come from the PoYo API reference. For what the model is and how it compares, start with the Ideogram 4.6 API overview.
Step 1: submit an Ideogram 4.6 API request with cURL
Create a key in the PoYo dashboard and export it as POYO_API_KEY. Keep it on your server, not in browser code.
curl https://api.poyo.ai/api/generate/submit \
-H "Authorization: Bearer $POYO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "ideogram-v4.6",
"input": {
"prompt": "A colorful storefront with a neon sign reading \"HELLO\""
}
}'
This uses the defaults: size: auto (about 2K), quality: medium, one image, so it costs 12 credits ($0.06). A successful submission returns code: 200 and a data object with task_id, status: "not_started" and created_time. That is a queued task, not an image. Check code in the body every time: some validation errors come back with HTTP 200 and code: 400.
Step 2: poll the task status
curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
Status moves through not_started, running, and then finished or failed. A finished task lists one entry per image in data.files, each with file_url and file_type: "image", and reports the charge in credits_amount. A failed task explains itself in error_message.
Step 3: a bounded Python polling loop
This loop checks both HTTP status and the body code, stops on failed, returns every image when n is above 1, and gives up after 10 minutes without resubmitting.
import os
import time
import requests
BASE = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]
def checked(response):
body = response.json()
if response.status_code >= 400 or body.get("code") != 200:
error = body.get("error") or {}
raise RuntimeError(f"PoYo error {body.get('code')}: {error.get('message', body)}")
return body["data"]
def run(model, input_body, max_wait=600):
task = checked(session.post(BASE + "/api/generate/submit",
json={"model": model, "input": input_body},
timeout=60))
task_id = task["task_id"]
deadline = time.monotonic() + max_wait
while time.monotonic() < deadline:
time.sleep(5)
task = checked(session.get(BASE + "/api/generate/status/" + task_id, timeout=60))
if task["status"] == "failed":
raise RuntimeError(task.get("error_message") or "generation failed")
if task["status"] == "finished":
images = [f["file_url"] for f in task.get("files", []) if f.get("file_type") == "image"]
return images, task.get("credits_amount")
raise TimeoutError("Still running, check this task later: " + task_id)
images, credits = run("ideogram-v4.6", {
"prompt": "A minimalist poster titled \"SUMMER JAZZ NIGHTS\", bold typography",
"size": "1728x2304",
"quality": "high",
"n": 2,
})
print(images, credits)
1728x2304 is a 3:4 size of 3,981,312 pixels, under the 4,194,304-pixel line, so the two images are billed at the 2K high rate: 2 × 20 = 40 credits ($0.20). A timeout means "check the same task ID again later". Resubmitting would start a second billable task. The same run() works for edits: pass "ideogram-v4.6-edit" as the model.
Every Ideogram 4.6 API input mode
All fields go inside input. The model ID and an optional callback_url sit at the top level.
Text-to-image at 4K
{
"model": "ideogram-v4.6",
"input": {
"prompt": "A minimalist poster titled \"SUMMER JAZZ NIGHTS\", bold typography",
"size": "2048x3072",
"quality": "high",
"n": 2
}
}
2048x3072 is 6,291,456 pixels, above 4,194,304, so this is the 4K tier and very_low is not allowed at this size.
Transparent background and a fixed seed
{
"model": "ideogram-v4.6",
"input": {
"prompt": "A flat sticker of a smiling coffee cup",
"size": "1:1 HD",
"quality": "low",
"background": "transparent",
"seed": 42
}
}
transparent returns an image with an alpha channel; opaque forces a solid background. Send the same body with the same seed to repeat a result.
Regular edit
{
"model": "ideogram-v4.6-edit",
"input": {
"prompt": "Replace the background with a blue photo studio",
"image_urls": [
"https://example.com/source.png"
]
}
}
A regular edit regenerates the image from the prompt. image_urls must be an array with exactly one image, as a public HTTP(S) URL or a base64 data URI. To send local files, upload them first with PoYo's file upload endpoint.
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
}
}
Up to 4 references are allowed, or 3 with a mask. A custom size is allowed here because this is a regular edit without a mask.
High-precision edit of the whole image
{
"model": "ideogram-v4.6-edit",
"input": {
"prompt": "Change only the date line to \"JULY 3-5 · RIVERSIDE PARK\". Keep everything else exactly the same.",
"image_urls": [
"https://example.com/poster.png"
],
"edit_precision": "high",
"context_window": "none",
"size": "auto",
"quality": "high"
}
}
This is the body of our launch-day edit (task 672JRU198S22NS8D, November 20, 2026), with the source URL replaced. The source was a 2304×3072 poster; the output kept that size and changed only the date line, and the task was charged 120 credits ($0.60), the 4K high edit rate.
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"
}
}
The mask must match the source dimensions and contain both black (edit) and white (keep) areas. With context_window: auto, only the region around the mask is edited at the source resolution. A mask that is too large falls back to whole-image editing.
Field validation rules
Validate on your side before submitting so bad requests fail fast:
| Field | Rule |
|---|---|
model | ideogram-v4.6 or ideogram-v4.6-edit |
prompt | Required, 1 to 10,000 characters, not only whitespace |
size | auto, 1:1, 1:1 HD, 4:3, 3:4, 16:9, 9:16 or WIDTHxHEIGHT with a lowercase x |
| Custom size | Each side 256 to 4096 and a multiple of 32; aspect ratio within 1:6 and 6:1 |
quality | very_low only when the output is at most 4,194,304 pixels |
n | Integer 1 to 8; strings and booleans are rejected |
image_urls | Edit only; array with exactly one image |
mask_url, edit_precision: high | Need size: auto (or no size) |
background | Rejected when edit_precision is high |
context_window: auto | Needs mask_url and edit_precision: high |
| Unknown fields | Rejected with an unsupported fields error |
Examples: 2304x3072 passes (both sides multiples of 32); 1296x3168 fails because 1296 is not a multiple of 32, even though Ideogram 4.5 accepted it; 4096x512 fails (ratio 8:1); very_low at 2048x3072 fails.
Errors worth handling
code | Meaning | What to do |
|---|---|---|
| 400 | Invalid parameters | Fix the body; do not retry unchanged |
| 401 | Missing or invalid API key | Check the Authorization: Bearer header |
| 402 | Insufficient credits | Top up, then resubmit |
| 429 | Rate limit exceeded | Back off and retry later |
| 500, 502, 503 | Server, upstream or availability error | Retry with backoff; check whether a task ID was already returned first |
A task that reaches failed carries the reason in error_message. See Error Codes for the full list.
Use a callback instead of polling
Add "callback_url": "https://your-app.example.com/poyo-webhook" at the top level of the body, not inside input. When the task finishes or fails, PoYo POSTs the task data to that URL, signed with HMAC-SHA256 in the X-Webhook-Signature header; the webhook docs give the signature rule. Keep a slow polling fallback for callbacks that never arrive.
How your first bill is calculated
The Ideogram 4.6 API bills per output image: price of the quality and size tier × n. 1 credit = $0.005.
| Request | Tier | Charge |
|---|---|---|
Defaults (auto, medium, n: 1) | Text-to-image medium 2K | 12 credits ($0.06) |
very_low, 3:4, n: 1 | Text-to-image very_low 2K | 1.6 credits ($0.008) |
high, 1728x2304, n: 2 | Text-to-image high 2K | 40 credits ($0.20) |
high, 2304x3072, n: 1 | Text-to-image high 4K | 40 credits ($0.20) |
High-precision edit of a 2304×3072 source, high | Edit high 4K | 120 credits ($0.60) |
The very_low and 2304x3072 rows match what our launch-day tasks were charged. For edits with size: auto, the price is quoted from the source image size and settled on the delivered image, never above the quote. The pricing post has more worked examples.
Frequently asked questions
Is the Ideogram 4.6 API compatible with the OpenAI SDK?
No. It is an async task API: submit to /api/generate/submit, then poll /api/generate/status/{task_id} or receive a callback. Plain requests, fetch or cURL work.
How do I edit an image with the Ideogram 4.6 API?
Call ideogram-v4.6-edit with one URL in image_urls and the change in prompt. Add edit_precision: high to keep the pixels you did not ask to change.
Can I send reference images to ideogram-v4.6?
No. On PoYo, references go in reference_image_urls on ideogram-v4.6-edit, up to 4, or 3 with a mask.
How many images does one Ideogram 4.6 API request return?
1 to 8, set with n. Each image is billed at the tier price.
Why was my Ideogram 4.6 API request rejected for size?
Custom sides must be multiples of 32 between 256 and 4096, and masks or high-precision edits need size: auto.