Перейти к основному содержанию
POST
Text-to-image: generate an image from a prompt (official channel)
🔒 Требуется группа GrokOfficial, доступ предоставляется по заявке: Grok Imagine Official не входит в группу Default; перед вызовом необходимо запросить доступ (включая Playground на этой странице). Без доступа или с pay-per-request Token каждый вызов возвращает 503. См. Обзор Grok Imagine Official — Настройка группы.
Интерактивный Playground справа позволяет протестировать эндпоинт напрямую. Введите свой API Key в Authorization (формат: Bearer sk-xxx), заполните prompt, выберите модель, resolution и aspect_ratio (а также quality для 2.0) и выполните отправку.
Когда использовать эту страницу: генерация изображений по тексту, одно изображение за вызов. Этот канал пока не поддерживает редактирование изображений — для редактирования на основе референсов или создания нескольких изображений за вызов используйте Grok Imagine Reverse.
⚠️ Три самые распространенные ошибки
  1. Используйте resolution, а не size: size не привязан к уровню разрешения, поэтому изображение генерируется и тарифицируется по умолчанию как 1k.
  2. Ошибки возвращают код ошибки: выход resolution / aspect_ratio за пределы диапазона возвращает 422, а quality: "high" возвращает 400 — в отличие от незаметного отката к значениям по умолчанию в reverse-канале.
  3. Всегда передавайте n = 1: для получения нескольких изображений отправляйте несколько параллельных запросов.
Все API генерации изображений являются синхронными: идентификатор асинхронной задачи отсутствует, поэтому при отключении клиента результат будет потерян, но запрос все равно тарифицируется. Генерация grok-imagine-image-2.0 при medium и 2K занимает около 60–80 секунд, поэтому установите таймаут клиента на 360 секунд. См. Примечания и рекомендации по Image API.

Примеры кода

Python (OpenAI SDK)

Python (requests)

cURL

Node.js (fetch)

Краткий справочник по параметрам

Цена за изображение (как у xAI):
Цены на модели синхронизированы с официальными сайтами и могут изменяться вслед за ними; таблица выше приведена исключительно для справки, а вкладка Тарифы на модели в верхней навигации имеет приоритет: Тарифы на модели.

Формат ответа

  • Каждый элемент в data[] содержит либо url, либо b64_json, в зависимости от response_format.
  • Скачивайте изображения по полученным ссылкам сразу же; не используйте эти ссылки для постоянного обращения.
  • usage является плейсхолдером (prompt_tokens всегда 1000 × image count) и не может использоваться для сверки — определяющими являются записи тарификации в консоли.
  • created всегда равен 0; не используйте его для измерения времени.

Связанная документация

Авторизации

Authorization
string
header
обязательно

API Key from the APIYI console (Token group must include GrokOfficial)

Тело

application/json
model
enum<string>
по умолчанию:grok-imagine-image
обязательно

Model ID:

  • grok-imagine-image — standard, $0.02 per image at every resolution
  • grok-imagine-image-quality — high quality, $0.05 / $0.06 / $0.07 at 1k / 1.5k / 2k
  • grok-imagine-image-2.0 — newer model, low $0.04 / $0.05 / $0.06, medium $0.06 / $0.07 / $0.08
Доступные опции:
grok-imagine-image,
grok-imagine-image-quality,
grok-imagine-image-2.0
prompt
string
обязательно

Prompt in any language. Describe the subject, scene, style, and lighting in detail

Пример:

"A photorealistic red wooden boat moored on a glassy alpine lake at dawn, mist over the water, snow-capped peaks behind, cinematic photography"

n
enum<integer>
по умолчанию:1

Image count. Fixed at 1 on this channel; call concurrently for more images

Доступные опции:
1
resolution
enum<string>
по умолчанию:1k

Resolution tier (lowercase), which also sets the price: 1k (default) / 1.5k / 2k.

Out-of-range values (such as 4k or 1K) return 422. Do not use size instead — it is not mapped to a resolution tier.

Доступные опции:
1k,
1.5k,
2k
aspect_ratio
enum<string>
по умолчанию:1:1

Output aspect ratio, default 1:1. Measured examples: grok-imagine-image at 1k + 3:2 outputs 1248×832; -quality at 2k + 9:16 outputs 1584×2816.

Out-of-range values (such as 5:7) return 422.

Доступные опции:
1:1,
16:9,
9:16,
4:3,
3:4,
3:2,
2:3
quality
enum<string>

Quality tier, only for grok-imagine-image-2.0: low (default) or medium ($0.02 more per image, slower).

high returns 400. The other two models take no quality.

Доступные опции:
low,
medium
response_format
enum<string>
по умолчанию:url

Response format: url (default; download and store the image right away) or b64_json (plain base64, no data: prefix)

Доступные опции:
url,
b64_json

Ответ

Image generated successfully

created
integer

Always 0; do not use it for timing

Пример:

0

data
object[]

Image results (one item on this channel)

usage
object

Placeholder — do not reconcile with it. prompt_tokens is always 1000 × image count; the console billing records are authoritative