Ideogram V3 API

Ideogram V3 API

Ideogram V3 рисует картинки по текстовому заданию и особенно хорошо справляется с надписями в кадре: афиши, обложки, упаковка, вывески, открытки, баннеры с заголовком. Подходит и для обычных иллюстраций и реалистичных фото.

Модель умеет подстраиваться под стиль: если передать до 4 картинок-референсов, она возьмёт с них цвета, настроение и манеру, а сюжет нарисует по заданию. За один запуск можно получить до 4 вариантов, а скорость генерации выбирается из трёх режимов - от быстрого и дешёвого до самого качественного.

Каждый вызов создаёт асинхронную операцию. Сохраните id из ответа и проверяйте по нему статус отдельным запросом.

Создание операции

• Endpoint: POST /api/v1/operations
• Авторизация: Authorization: Bearer brth_...
• Выполнение асинхронное: запрос сразу возвращает id и стартовый статус queued.

Сценарии:

• Генерация по тексту - только задание и настройки.
• Генерация с референсами стиля - плюс image_urls с 1-4 картинками, чей стиль нужно повторить.
• Несколько вариантов и негативный промпт - num_images до 4 и список того, чего в кадре быть не должно.

Тело запроса

{
  "tool": "ideogram-v3",
  "input": {
    "prompt": "...",
    "rendering_speed": "BALANCED",
    "aspect_ratio": "1:1",
    "num_images": 1,
    "expand_prompt": true
  }
}

• tool - slug нейросети, всегда "ideogram-v3".
• input - параметры запуска. Все поля передаются прямо внутри этого объекта, без дополнительной вложенности.
• Необязательные image_urls, use_negative_prompt и negative_prompt добавляются по сценарию.

Параметры

Примеры запросов

Генерация по тексту

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "ideogram-v3",
  "input": {
    "prompt": "Фото на кухне: на светлом деревянном столе у окна картонная коробка чая, рядом чашка. На коробке крупно написано «Иван-чай». Спокойные зелёные и кремовые цвета, мягкий дневной свет",
    "rendering_speed": "BALANCED",
    "aspect_ratio": "1:1",
    "num_images": 1,
    "expand_prompt": true
  }
}'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'ideogram-v3',
    input: {
      prompt:
        'Фото на кухне: на светлом деревянном столе у окна картонная коробка чая, рядом чашка. На коробке крупно написано «Иван-чай». Спокойные зелёные и кремовые цвета, мягкий дневной свет',
      rendering_speed: 'BALANCED',
      aspect_ratio: '1:1',
      num_images: 1,
      expand_prompt: true,
    },
  }),
})

const data = await response.json()
console.log(data.id, data.status)

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'ideogram-v3',
        'input': {
            'prompt': 'Фото на кухне: на светлом деревянном столе у окна картонная коробка чая, рядом чашка. На коробке крупно написано «Иван-чай». Спокойные зелёные и кремовые цвета, мягкий дневной свет',
            'rendering_speed': 'BALANCED',
            'aspect_ratio': '1:1',
            'num_images': 1,
            'expand_prompt': True,
        },
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Генерация с референсами стиля

Афиша в стиле двух летних фотографий. Режим TURBO, один вариант - 6 ₽. expand_prompt: false, чтобы модель не дописывала к заданию своё.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "ideogram-v3",
  "input": {
    "prompt": "Летний постер дачного фестиваля: гриль, дым, деревянный забор, крупная надпись «ДАЧА ФЕСТ» и ниже «12 июля»",
    "image_urls": [
      "https://cdn.example.com/style-summer-1.jpg",
      "https://cdn.example.com/style-summer-2.webp"
    ],
    "rendering_speed": "TURBO",
    "aspect_ratio": "3:4",
    "num_images": 1,
    "expand_prompt": false
  }
}'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'ideogram-v3',
    input: {
      prompt:
        'Летний постер дачного фестиваля: гриль, дым, деревянный забор, крупная надпись «ДАЧА ФЕСТ» и ниже «12 июля»',
      image_urls: [
        'https://cdn.example.com/style-summer-1.jpg',
        'https://cdn.example.com/style-summer-2.webp',
      ],
      rendering_speed: 'TURBO',
      aspect_ratio: '3:4',
      num_images: 1,
      expand_prompt: false,
    },
  }),
})

const data = await response.json()

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'ideogram-v3',
        'input': {
            'prompt': 'Летний постер дачного фестиваля: гриль, дым, деревянный забор, крупная надпись «ДАЧА ФЕСТ» и ниже «12 июля»',
            'image_urls': [
                'https://cdn.example.com/style-summer-1.jpg',
                'https://cdn.example.com/style-summer-2.webp',
            ],
            'rendering_speed': 'TURBO',
            'aspect_ratio': '3:4',
            'num_images': 1,
            'expand_prompt': False,
        },
    },
    timeout=30,
)

print(response.json())

Несколько вариантов с негативным промптом

Четыре варианта обложки в режиме QUALITY - 72 ₽. Негативный промпт убирает типичные огрехи с текстом.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "ideogram-v3",
  "input": {
    "prompt": "Обложка подкаста о путешествиях: рюкзак и старая карта на деревянном столе, сверху крупная надпись «В дороге», тёплые цвета",
    "rendering_speed": "QUALITY",
    "aspect_ratio": "16:9",
    "num_images": 4,
    "expand_prompt": true,
    "use_negative_prompt": true,
    "negative_prompt": "размытый текст, лишние буквы, водяные знаки"
  }
}'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'ideogram-v3',
    input: {
      prompt:
        'Обложка подкаста о путешествиях: рюкзак и старая карта на деревянном столе, сверху крупная надпись «В дороге», тёплые цвета',
      rendering_speed: 'QUALITY',
      aspect_ratio: '16:9',
      num_images: 4,
      expand_prompt: true,
      use_negative_prompt: true,
      negative_prompt: 'размытый текст, лишние буквы, водяные знаки',
    },
  }),
})

const data = await response.json()

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'ideogram-v3',
        'input': {
            'prompt': 'Обложка подкаста о путешествиях: рюкзак и старая карта на деревянном столе, сверху крупная надпись «В дороге», тёплые цвета',
            'rendering_speed': 'QUALITY',
            'aspect_ratio': '16:9',
            'num_images': 4,
            'expand_prompt': True,
            'use_negative_prompt': True,
            'negative_prompt': 'размытый текст, лишние буквы, водяные знаки',
        },
    },
    timeout=30,
)

print(response.json())

Примеры ответов

Ответ после создания

{
  "id": "op_uuid-123",
  "status": "queued",
  "tool": "ideogram-v3",
  "cost": 6,
  "balance_after": 494,
  "created_at": "2026-09-30T21:32:08.559809+00:00"
}

Ответ после завершения

{
  "id": "op_uuid-123",
  "status": "completed",
  "tool": "ideogram-v3",
  "cost": 6,
  "created_at": "2026-09-30T21:32:08.559809+00:00",
  "completed_at": "2026-09-30T21:32:33.685506+00:00",
  "result": {
    "type": "image",
    "urls": [
      "https://storage.bratuha.ru/results/ideogram-v3/image-1.png"
    ]
  },
  "error_message": null
}

Ответ при ошибке

{
  "id": "op_uuid-123",
  "status": "failed",
  "tool": "ideogram-v3",
  "cost": 6,
  "created_at": "2026-09-30T21:32:08.559809+00:00",
  "completed_at": "2026-09-30T21:32:15.204391+00:00",
  "result": null,
  "error_message": "Ваш запрос не прошел модерацию."
}

Проверка статуса

Сохраните id из ответа на создание и запрашивайте статус операции по нему:

GET /api/v1/operations/{id}

curl -H "Authorization: Bearer brth_ваш_ключ" \
  https://bratuha.ru/api/v1/operations/op_uuid-123

async function waitForResult(id: string) {
  while (true) {
    const response = await fetch(`https://bratuha.ru/api/v1/operations/${id}`, {
      headers: { Authorization: 'Bearer brth_ваш_ключ' },
    })
    const operation = await response.json()
    if (operation.status === 'completed' || operation.status === 'failed') {
      return operation
    }
    await new Promise((resolve) => setTimeout(resolve, 5000))
  }
}

Статус меняется с queued на processing, а затем на completed или failed. Обычно картинки готовы за 25-40 секунд. Опрашивать одну операцию можно не чаще раза в секунду, разумный интервал - 3-5 секунд.

Формат результата

{
  "type": "image",
  "urls": [
    "https://storage.bratuha.ru/results/ideogram-v3/image-1.png",
    "https://storage.bratuha.ru/results/ideogram-v3/image-2.png"
  ]
}

• type - всегда "image".
• urls - массив ссылок на PNG. Ссылок столько, сколько вы указали в num_images: при num_images: 1 - одна, при num_images: 4 - четыре.

Размер картинки задаётся пропорциями aspect_ratio: например, при 3:4 получается 864×1152 пикселей.

Ценообразование

Цена считается за каждую картинку и зависит от режима rendering_speed: TURBO - 6 ₽, BALANCED - 12 ₽, QUALITY - 18 ₽ за изображение. Итог - цена режима, умноженная на num_images.

Пропорции, референсы стиля, улучшение промпта и негативный промпт на цену не влияют. Стоимость списывается при создании операции и приходит в поле cost ответа.

Ограничения и практические заметки

• POST /api/v1/operations не идемпотентен: каждый повторный запрос создаёт новую оплаченную операцию. Если ответ потерялся, не повторяйте запрос вслепую.
• Все операции асинхронные: сначала приходит queued, результат забирается по id.
• Референсы передаются только ссылками http/https, которые открываются без авторизации. Форматы - JPG, JPEG, PNG или WebP, не больше 4 ссылок и до 10 МБ в сумме.
• num_images - только целое число от 1 до 4. Дробное значение или число больше 4 вернёт 400 validation_error.
• Крупные надписи модель пишет уверенно, в том числе по-русски. Мелкие строки кириллицей чаще выходят с ошибками в буквах. Если важен каждый символ, делайте текст крупнее и короче или запросите сразу несколько вариантов.
• Референс передаёт стиль, а не предметы: если нужна конкретная вещь с фото, опишите её словами в prompt.
• negative_prompt без use_negative_prompt: true молча игнорируется - ошибки не будет, но и эффекта тоже.
• Если модель слишком «додумывает» сцену, выключите expand_prompt: так результат ближе к вашему тексту. Для коротких заданий из пары слов улучшение, наоборот, полезно.
• Изредка запрос отклоняется модерацией с ошибкой «Ваш запрос не прошел модерацию». Переформулируйте задание.