Grok Imagine 2.0 Ext
Grok Imagine 2.0 Ext: генерация изображений
- Асинхронный text-to-image; опрос результата по task_id
- 1–12 изображений за запрос; тарификация по фактически доставленным ($0.08 / шт.)
- Только вывод url; без image-to-image / streaming
- Ссылки на изображения действительны 72 часа
POST
Text-to-image · асинхронные задачи. Отправьте
Имя модели фиксировано:
POST /v1/images/generations, затем опрашивайте Получить статус задачи.Имя модели фиксировано:
grok-imagine-2.0-ext. Не поддерживается: референсные изображения, stream и значения response_format, кроме url.Возможности и ограничения
Аутентификация и рекомендуемые заголовки
string
обязательно
Bearer-токен. Получите ключ на странице API Key.
Параметры запроса
string
обязательно
Фиксированное значение:
grok-imagine-2.0-extstring
обязательно
Промпт. После trim не должен быть пустым. Выполните trim перед отправкой.
integer
по умолчанию:"1"
Количество изображений:
1–12. Явный 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.string
по умолчанию:"url"
Допускается только
url. Можно опустить. b64_json / base64 → 400 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
- Для отображения используйте
url[]; приn>1обходите все элементы - Сопоставляйте по индексу только если
image_ids.length === url.length - Отсутствие
image_idsне мешает отображению - Ссылки действуют 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. Не показывайте конечным пользователям внутренности аутентификации.