
Это руководство по Ideogram 4.6 API проведёт вас от API-ключа до готового изображения на cURL и Python, а затем разберёт каждый режим ввода, который принимает схема PoYo: генерацию по тексту в пресетных или пользовательских размерах, прозрачный фон, обычные правки, правки по маске, референсные изображения и правки высокой точности. Для генерации по тексту используется ID модели ideogram-v4.6, для редактирования — ideogram-v4.6-edit; оба указаны на странице модели Ideogram 4.6.
Правила полей взяты из справочника PoYo API. О том, что представляет собой модель и как она соотносится с другими, читайте в обзоре Ideogram 4.6 API.
Шаг 1: отправьте запрос к Ideogram 4.6 API через cURL
Создайте ключ в панели PoYo и экспортируйте его как POYO_API_KEY. Храните его на сервере, а не в коде браузера.
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\""
}
}'
Здесь используются значения по умолчанию: size: auto (около 2K), quality: medium, одно изображение, поэтому запрос стоит 12 credits ($0.06). Успешная отправка возвращает code: 200 и объект data с task_id, status: "not_started" и created_time. Это задача в очереди, а не изображение. Каждый раз проверяйте code в теле ответа: некоторые ошибки валидации приходят с HTTP 200 и code: 400.
Шаг 2: опросите статус задачи
curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
Статус проходит через not_started, running, а затем finished или failed. Завершённая задача перечисляет по одной записи на изображение в data.files, каждую с file_url и file_type: "image", и сообщает списание в credits_amount. Задача со статусом failed объясняет причину в error_message.
Шаг 3: ограниченный по времени цикл опроса на Python
Этот цикл проверяет и HTTP-статус, и code в теле, останавливается на failed, возвращает все изображения, когда n больше 1, и прекращает ожидание через 10 минут без повторной отправки.
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 — размер 3:4 в 3,981,312 пикселей, ниже границы 4,194,304 пикселей, поэтому два изображения тарифицируются по ставке 2K high: 2 × 20 = 40 credits ($0.20). Таймаут означает «проверьте тот же ID задачи позже». Повторная отправка запустила бы вторую платную задачу. Та же функция run() работает и для правок: передайте "ideogram-v4.6-edit" в качестве модели.
Все режимы ввода Ideogram 4.6 API
Все поля передаются внутри input. ID модели и необязательный callback_url находятся на верхнем уровне.
Генерация по тексту в 4K
{
"model": "ideogram-v4.6",
"input": {
"prompt": "A minimalist poster titled \"SUMMER JAZZ NIGHTS\", bold typography",
"size": "2048x3072",
"quality": "high",
"n": 2
}
}
2048x3072 — это 6,291,456 пикселей, больше 4,194,304, поэтому это уровень 4K, и very_low при таком размере не допускается.
Прозрачный фон и фиксированный 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 возвращает изображение с альфа-каналом; opaque принудительно задаёт сплошной фон. Отправьте то же тело с тем же seed, чтобы повторить результат.
Обычная правка
{
"model": "ideogram-v4.6-edit",
"input": {
"prompt": "Replace the background with a blue photo studio",
"image_urls": [
"https://example.com/source.png"
]
}
}
Обычная правка заново генерирует изображение по промпту. image_urls должен быть массивом ровно с одним изображением — публичным HTTP(S) URL или base64 data URI. Чтобы отправить локальные файлы, сначала загрузите их через эндпоинт загрузки файлов PoYo.
Рестайлинг по референсному изображению
{
"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
}
}
Допускается до 4 референсов или 3 с маской. Пользовательский size здесь разрешён, потому что это обычная правка без маски.
Правка высокой точности для всего изображения
{
"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"
}
}
Это тело нашей правки в день запуска (задача 672JRU198S22NS8D, 20 ноября 2026 года) с заменённым URL исходника. Исходником был постер 2304×3072; результат сохранил этот размер и изменил только строку с датой, а за задачу было списано 120 credits ($0.60) — ставка правки 4K high.
Локальная правка по маске
{
"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"
}
}
Маска должна совпадать по размерам с исходником и содержать как чёрные (правка), так и белые (сохранить) области. С context_window: auto редактируется только область вокруг маски в разрешении исходника. Слишком большая маска приводит к откату на редактирование всего изображения.
Правила валидации полей
Проверяйте запросы на своей стороне перед отправкой, чтобы некорректные запросы отклонялись сразу:
| Поле | Правило |
|---|---|
model | ideogram-v4.6 или ideogram-v4.6-edit |
prompt | Обязательно, от 1 до 10,000 символов, не только пробелы |
size | auto, 1:1, 1:1 HD, 4:3, 3:4, 16:9, 9:16 или WIDTHxHEIGHT со строчной x |
| Пользовательский размер | Каждая сторона от 256 до 4096 и кратна 32; соотношение сторон в пределах от 1:6 до 6:1 |
quality | very_low только когда результат не больше 4,194,304 пикселей |
n | Целое число от 1 до 8; строки и булевы значения отклоняются |
image_urls | Только для правок; массив ровно с одним изображением |
mask_url, edit_precision: high | Требуют size: auto (или отсутствия size) |
background | Отклоняется, когда edit_precision равно high |
context_window: auto | Требует mask_url и edit_precision: high |
| Неизвестные поля | Отклоняются с ошибкой unsupported fields |
Примеры: 2304x3072 проходит (обе стороны кратны 32); 1296x3168 не проходит, потому что 1296 не кратно 32, хотя Ideogram 4.5 его принимал; 4096x512 не проходит (соотношение 8:1); very_low при 2048x3072 не проходит.
Ошибки, которые стоит обрабатывать
code | Значение | Что делать |
|---|---|---|
| 400 | Некорректные параметры | Исправьте тело; не повторяйте без изменений |
| 401 | API-ключ отсутствует или недействителен | Проверьте заголовок Authorization: Bearer |
| 402 | Недостаточно кредитов | Пополните баланс и отправьте повторно |
| 429 | Превышен лимит запросов | Сделайте паузу и повторите позже |
| 500, 502, 503 | Ошибка сервера, апстрима или доступности | Повторите с backoff; сначала проверьте, не был ли уже возвращён ID задачи |
Задача, дошедшая до failed, содержит причину в error_message. Полный список см. в Error Codes.
Используйте callback вместо опроса
Добавьте "callback_url": "https://your-app.example.com/poyo-webhook" на верхний уровень тела, а не внутрь input. Когда задача завершится или завершится ошибкой, PoYo отправит POST с данными задачи на этот URL с подписью HMAC-SHA256 в заголовке X-Webhook-Signature; правило подписи описано в документации по вебхукам. Оставьте медленный опрос как запасной вариант для callback, которые так и не придут.
Как рассчитывается ваш первый счёт
Ideogram 4.6 API тарифицирует каждое выходное изображение: цена уровня качества и размера × n. 1 credit = $0.005.
| Запрос | Уровень | Списание |
|---|---|---|
По умолчанию (auto, medium, n: 1) | Генерация medium 2K | 12 credits ($0.06) |
very_low, 3:4, n: 1 | Генерация very_low 2K | 1.6 credits ($0.008) |
high, 1728x2304, n: 2 | Генерация high 2K | 40 credits ($0.20) |
high, 2304x3072, n: 1 | Генерация high 4K | 40 credits ($0.20) |
Правка высокой точности исходника 2304×3072, high | Правка high 4K | 120 credits ($0.60) |
Строки very_low и 2304x3072 совпадают с тем, что было списано за наши задачи в день запуска. Для правок с size: auto цена рассчитывается по размеру исходного изображения и окончательно фиксируется по выданному изображению, но никогда не превышает расчёт. Больше примеров — в статье о ценах.
Часто задаваемые вопросы
Совместим ли Ideogram 4.6 API с OpenAI SDK?
Нет. Это асинхронный API задач: отправьте запрос на /api/generate/submit, затем опрашивайте /api/generate/status/{task_id} или получите callback. Подойдут обычные requests, fetch или cURL.
Как отредактировать изображение через Ideogram 4.6 API?
Вызовите ideogram-v4.6-edit с одним URL в image_urls и описанием изменения в prompt. Добавьте edit_precision: high, чтобы сохранить пиксели, которые вы не просили менять.
Можно ли отправлять референсные изображения в ideogram-v4.6?
Нет. В PoYo референсы передаются в reference_image_urls модели ideogram-v4.6-edit, до 4 или 3 с маской.
Сколько изображений возвращает один запрос к Ideogram 4.6 API?
От 1 до 8, задаётся через n. Каждое изображение тарифицируется по цене уровня.
Почему мой запрос к Ideogram 4.6 API отклонён из-за размера?
Пользовательские стороны должны быть кратны 32 и находиться в диапазоне от 256 до 4096, а маски и правки высокой точности требуют size: auto.