how-tos

Ideogram 4.6 API: руководство — первое изображение и правка на cURL и Python

Poyo.ai Team
8 min read
Share:

Руководство по Ideogram 4.6 API с cURL и Python

Это руководство по 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 редактируется только область вокруг маски в разрешении исходника. Слишком большая маска приводит к откату на редактирование всего изображения.

Правила валидации полей

Проверяйте запросы на своей стороне перед отправкой, чтобы некорректные запросы отклонялись сразу:

ПолеПравило
modelideogram-v4.6 или ideogram-v4.6-edit
promptОбязательно, от 1 до 10,000 символов, не только пробелы
sizeauto, 1:1, 1:1 HD, 4:3, 3:4, 16:9, 9:16 или WIDTHxHEIGHT со строчной x
Пользовательский размерКаждая сторона от 256 до 4096 и кратна 32; соотношение сторон в пределах от 1:6 до 6:1
qualityvery_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Некорректные параметрыИсправьте тело; не повторяйте без изменений
401API-ключ отсутствует или недействителенПроверьте заголовок 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 2K12 credits ($0.06)
very_low, 3:4, n: 1Генерация very_low 2K1.6 credits ($0.008)
high, 1728x2304, n: 2Генерация high 2K40 credits ($0.20)
high, 2304x3072, n: 1Генерация high 4K40 credits ($0.20)
Правка высокой точности исходника 2304×3072, highПравка high 4K120 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.

Share: