Skip to main content
POST
Text-to-image · асинхронные задачи. Отправьте POST /v1/images/generations, затем опрашивайте Получить статус задачи.
Имя модели фиксировано: grok-imagine-2.0-ext. Не поддерживается: референсные изображения, stream и значения response_format, кроме url.
Не помещайте API-ключи в браузерные бандлы (VITE_* / NEXT_PUBLIC_*, LocalStorage и т.п.). Из браузера вызывайте свой BFF; ключ APIMart храните на сервере.

Возможности и ограничения

Аутентификация и рекомендуемые заголовки

string
обязательно
Bearer-токен. Получите ключ на странице API Key.

Параметры запроса

string
обязательно
Фиксированное значение: grok-imagine-2.0-ext
string
обязательно
Промпт. После trim не должен быть пустым. Выполните trim перед отправкой.
integer
по умолчанию:"1"
Количество изображений: 112. Явный 0 вызывает ошибку. При отсутствии параметра — 1.
string
Соотношение сторон. Предпочитайте строковые соотношения (в UI показывайте только соотношения):Пиксельные алиасы: 1024x1024 (1:1), 1024x1792 (2:3), 1792x1024 (3:2), 720x1280 (9:16), 1280x720 (16:9).Значения вне белого списка возвращают 400 invalid_size (например 1:2, 2:1, 4:5, auto).
Фактические пиксели для данного соотношения могут отличаться от таблицы алиасов (например, 1:1 может вернуть 1408×1408). Ориентируйтесь на возвращённое изображение; не переписывайте size по измеренным пикселям.
string
Поле режима качества. Проверенное значение: quality.
  • Можно опустить (модель по умолчанию в режиме quality), или
  • Явно передать resolution: "quality"
Не является уровнем пикселей 1K / 2K / 4K; кадрирование задаётся через size.
Не отправляйте публичное поле quality — получите 400 invalid_quality. Используйте resolution.
string
по умолчанию:"url"
Допускается только url. Можно опустить. b64_json / base64400 invalid_response_format.
string
Опциональный публичный HTTPS base URL. При терминальном статусе платформа делает POST на {webhook}/callback. Только для серверной интеграции — см. Webhook.

Неподдерживаемые параметры

Собирайте запросы по белому списку; не пробрасывайте целиком generic-объект формы от других моделей.

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

Минимальный

Рекомендуемый

Ответ на submit

Рекомендуется X-APIMart-Response-Version: 2026-07-27. Успех — HTTP 202; ID задачи в data.id (не полагайтесь на устаревший data[0].task_id). Сохраните:
  • data.id для опроса
  • request_id для отладки на стороне шлюза
  • Idempotency-Key для безопасных повторов, когда исход неизвестен
  • исходные параметры запроса для UI / поддержки

Идемпотентность и безопасные повторы

Генерация изображений тарифицируется — настоятельно рекомендуется Idempotency-Key (1–191 печатных ASCII-символа; проще всего UUID; хранится ~24 часа). При сетевом таймауте POST, когда нельзя понять, принял ли сервер задачу, не создавайте сразу новый key — повторите с тем же key / body / версией ответа.

Опрос задач

Опциональный language: zh / en / ko / ja (только локализация сообщений об ошибках). См. Получить статус задачи.

Статусы

Опрашивайте примерно каждые 2 секунды; лимит около 10 минут или 120 попыток. При 429 соблюдайте Retry-After. Задачи хранятся ~3 дня по умолчанию — сохраняйте task id, если клиентский таймаут истёк.

Пример завершённой задачи

Разбор url и image_ids

  1. Для отображения используйте url[]; при n>1 обходите все элементы
  2. Сопоставляйте по индексу только если image_ids.length === url.length
  3. Отсутствие image_ids не мешает отображению
  4. Ссылки действуют 72 часа — скачивайте своевременно; также ориентируйтесь на expires_at

Тарификация

Базовая цена $0.08 за изображение (успешные доставки):
  • В UI до отправки показывайте «оценку»; итоговая сумма в USD — data.cost
  • data.credits_cost — представление в кредитах (сейчас ≈ USD × 10)
  • Предсписание по запрошенному количеству; финальный расчёт по успешным (частичный возврат при частичном сбое)
  • Полный сбой: cost=0, предсписание возвращено
  • Не стройте ключи цен из resolution; у этой модели фиксированная цена за изображение

Webhook (опционально)

  • Укажите base URL; платформа вызывает {base}/callback
  • Должен быть публичным и проходить проверки SSRF
  • Если задан webhook_secret, подпись — hex(HMAC-SHA256(secret, raw_body)) по сырым байтам
  • Тело callback совпадает с data из запроса статуса задачи (без обёртки {code,data})
  • Всё равно держите низкочастотный опрос как fallback

Частые ошибки

Для UI предпочтительнее error.message. Не показывайте конечным пользователям внутренности аутентификации.

Отличия от 1.5 (кратко)