how-tos

Ideogram 4.6 API Guide: First Image and Edit in cURL and Python

Poyo.ai Team
9 min read
Share:

Ideogram 4.6 API guide with cURL and Python

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:

FieldRule
modelideogram-v4.6 or ideogram-v4.6-edit
promptRequired, 1 to 10,000 characters, not only whitespace
sizeauto, 1:1, 1:1 HD, 4:3, 3:4, 16:9, 9:16 or WIDTHxHEIGHT with a lowercase x
Custom sizeEach side 256 to 4096 and a multiple of 32; aspect ratio within 1:6 and 6:1
qualityvery_low only when the output is at most 4,194,304 pixels
nInteger 1 to 8; strings and booleans are rejected
image_urlsEdit only; array with exactly one image
mask_url, edit_precision: highNeed size: auto (or no size)
backgroundRejected when edit_precision is high
context_window: autoNeeds mask_url and edit_precision: high
Unknown fieldsRejected 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

codeMeaningWhat to do
400Invalid parametersFix the body; do not retry unchanged
401Missing or invalid API keyCheck the Authorization: Bearer header
402Insufficient creditsTop up, then resubmit
429Rate limit exceededBack off and retry later
500, 502, 503Server, upstream or availability errorRetry 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.

RequestTierCharge
Defaults (auto, medium, n: 1)Text-to-image medium 2K12 credits ($0.06)
very_low, 3:4, n: 1Text-to-image very_low 2K1.6 credits ($0.008)
high, 1728x2304, n: 2Text-to-image high 2K40 credits ($0.20)
high, 2304x3072, n: 1Text-to-image high 4K40 credits ($0.20)
High-precision edit of a 2304×3072 source, highEdit high 4K120 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.

Share: