Grok Imagine Image API: первое изображение с curl и Python

Чтобы использовать Grok Imagine Image API, отправьте prompt и ID модели на endpoint генерации xAI, затем сохраните результат. Начните с одного выхода и явных настроек; после проверки ответа добавляйте пакетную обработку и редактирование.

Примеры используют прямой API xAI и grok-imagine-image-2.0, согласно документации генерации, проверенной 8 сентября 2026 года. Платная генерация для статьи не выполнялась. Нужны ключ с доступом, серверная среда и хранилище изображений. На дату проверки Grok Imagine не указан в каталоге Ofox, и ключ Ofox нельзя использовать для прямого xAI API.

Один запрос через curl

Задайте XAI_API_KEY обычным для проекта способом хранения секретов. Выполняйте запрос на сервере или в терминале: ключ не должен попадать в публичный браузерный код. Запуск создаёт оплачиваемое использование API.

curl --fail-with-body --silent --show-error \
  --max-time 180 \
  https://api.x.ai/v1/images/generations \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "Studio photograph of a matte blue ceramic cup on a pale stone shelf, soft light from the left, no lettering",
    "n": 1,
    "aspect_ratio": "1:1",
    "resolution": "1k",
    "quality": "low",
    "response_format": "url"
  }' \
  -o grok-image-response.json

Текст prompt — пример задания, не измеренный лучший вариант. Тайм-аут 180 секунд выбран приложением и не обещает такую скорость сервиса. Проверьте код завершения команды и сохранённый JSON. Сначала убедитесь, что ответ не содержит ошибку, и только затем скачивайте изображение.

Сохранённый ответ помогает расследовать сбой: вместо загрузки несуществующего URL можно увидеть исходные данные ошибки.

Сохранение изображения в Python

Установите requests в окружении проекта. Пример запрашивает base64, проверяет наличие изображения и записывает байты без предположения о формате.

import base64
import os
from pathlib import Path

import requests

payload = {
    "model": "grok-imagine-image-2.0",
    "prompt": (
        "Studio photograph of a matte blue ceramic cup on a pale "
        "stone shelf, soft light from the left, no lettering"
    ),
    "n": 1,
    "aspect_ratio": "1:1",
    "resolution": "1k",
    "quality": "low",
    "response_format": "b64_json",
}
response = requests.post(
    "https://api.x.ai/v1/images/generations",
    headers={"Authorization": f"Bearer {os.environ['XAI_API_KEY']}"},
    json=payload,
    timeout=(10, 180),
)
response.raise_for_status()
body = response.json()
images = body.get("data", [])
if not images or not images[0].get("b64_json"):
    raise RuntimeError("No base64 image returned; inspect response metadata")
image_bytes = base64.b64decode(images[0]["b64_json"], validate=True)
# Keep raw bytes until your image decoder identifies the returned format.
output = Path("grok-image-output.bin")
output.write_bytes(image_bytes)
print(f"Saved {len(image_bytes)} bytes to {output}")

Расширение .bin намеренное. В приложении передайте байты декодеру изображений, проверьте формат и размеры, затем выберите расширение и media type. Называть непроверенный файл PNG или JPEG преждевременно.

API также возвращает URL, но такие ссылки временные. Если материал нужен надолго, своевременно перенесите его в своё хранилище. См. форматы ответа.

Что записать перед пакетной генерацией

Сначала определите пропорции, качество по бюджету и число выходов. Для каждой задачи сохраняйте:

Генерация и правка должны быть отдельными операциями. Для правки нужны входные изображения, другая схема и собственный бюджет. Произвольное поле image в запросе генерации не гарантирует поддержку у каждого поставщика. Используйте документацию редактирования.

Перед повторной отправкой

Различайте отказ соединения, HTTP-ошибку и неожиданные данные в успешном ответе. При ошибке авторизации проверьте хост и источник ключа. При ошибке валидации сократите запрос и сопоставьте отклонённое поле со схемой API.

Тайм-аут после отправки не сообщает наверняка, завершилась ли генерация на сервере. Не повторяйте платную операцию автоматически, не разобравшись. Сохраняйте метаданные ответа у задачи и делайте повторную отправку осознанной; заголовок Authorization в лог не записывайте.

При ответе, связанном с модерацией, уточните правила и измените запрос так, чтобы им соответствовать. Цикл повторов не исправляет неподдерживаемое задание. Общие случаи есть в руководстве по ошибкам генерации, но имена параметров берите у текущего поставщика.

Интеграция в приложение

Соберите специфические поля поставщика в небольшом адаптере. Остальное приложение может оперировать заданием, референсом и формой выхода. Так при сравнении провайдеров сохраняется один brief, а меняется адаптер, а не код по всему проекту. В качестве другого примера полезен процесс работы с FLUX.

Перед увеличением объёма рассчитайте стоимость Image 2.0. При использовании старого алиаса проверьте миграцию quality.