Перейти к основному содержанию
POST
Text-to-image: generate images from a text prompt
🔒 Недоступно по умолчанию: Grok Imagine 2 не входит в группу Default. Модель находится в отдельной группе Grok_imagine_Reverse, и для её вызова (включая Playground на этой странице) необходимо предварительно запросить доступ. Без этого каждый вызов возвращает 503.Политика безопасности контента для этого семейства моделей существенно отличается от других моделей на платформе, и некоторые категории не фильтруются. Поэтому для снижения комплаенс-рисков доступ предоставляется выборочно: действующие клиенты с суммарными расходами от $1,000+ могут подключить его, описав свой сценарий использования службе поддержки; остальные пользователи подают заявку через поддержку в WeCom с описанием сценария использования и применяемых мер модерации контента. Полный процесс: Обзор Grok Imagine 2 — Настройка группы.
Интерактивный Playground справа позволяет протестировать эндпоинт напрямую. Введите ваш API-ключ в поле Authorization (формат: Bearer sk-xxx), заполните prompt, выберите aspect_ratio / resolution и отправьте запрос.
Когда использовать эту страницу: генерация изображений по тексту только на основе prompt — без загрузки изображений. Чтобы изменить существующее изображение или объединить несколько, используйте эндпоинт редактирования изображений.
⚠️ Не отправляйте референсные изображения в этот эндпоинтПередача image / image_url / images сюда не вызывает ошибки. Запрос возвращает 200 и генерирует совершенно новое изображение по prompt — референс незаметно отбрасывается, а тарификация всё равно списывается.При отсутствии сигнала об ошибке это обычно обнаруживается только тогда, когда кто-то замечает, что результат не имеет ничего общего с исходным изображением. В любых сценариях с референсным изображением необходимо использовать /v1/images/edits.
⚠️ Недопустимые параметры не вызывают ошибокНедопустимые aspect_ratio (например, 5:7), resolution (например, 1K, 1024x1024) и response_format (например, base64) — все они незаметно сбрасываются к значениям по умолчанию и всё равно возвращают изображение. Если результат не соответствует ожиданиям, сначала проверьте написание параметров — обратите внимание, что значения resolution указываются в нижнем регистре: 1k / 2k.Одно исключение: resolution: "4k" возвращает 503 model_service_unavailable, что означает, что уровень не поддерживается, а не то, что канал недоступен. Повторные попытки не помогут.
Все API для работы с изображениями являются синхронными: здесь нет идентификатора асинхронной задачи, поэтому при отключении клиента результат теряется, тогда как тарификация за запрос всё равно выполняется. Генерация в 1K занимает около 9 секунд, а в 2K — около 15–17 секунд, поэтому установите таймаут клиента на 360 секунд — см. Рекомендации по Image API.

Примеры кода

Python (OpenAI SDK)

Python (сырые запросы)

cURL

Node.js (нативный fetch)

JavaScript в браузере

Справочник по параметрам

Фактическое количество пикселей на выходе для каждого соотношения сторон:
seed не поддерживается (принимается без ошибки, но не влияет на результат — результаты не воспроизводимы), как и mask inpainting. Поля в стиле OpenAI, такие как size / quality / style, игнорируются без сообщения об ошибке.

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

Подводные камни полей ответа
  • Каждая запись data[] содержит либо url либо b64_json в зависимости от response_format — никогда не оба сразу.
  • revised_prompt не возвращается, как и respect_moderation / model. Не предполагайте, что они существуют.
  • b64_json — это сырой base64 без префикса data:image/...;base64, — декодируйте его напрямую.
  • created всегда 0 и не может использоваться как временная метка.
  • При n > 1 массив data содержит несколько записей — не считывайте только data[0].
usage не может использоваться для сверки: prompt_tokens всегда равен 1000 x n, независимо от фактической длины prompt. Это семейство тарифицируется по фиксированной ставке за изображение ($0.02 / $0.045); используйте записи тарификации в консоли APIYI для фактических списаний.

Авторизации

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

API Key created in the APIYI Console

Тело

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

Model ID. The quality variant delivers higher fidelity at a higher price

Доступные опции:
grok-imagine-image,
grok-imagine-image-quality
prompt
string
обязательно

Prompt, English or Chinese. Describe 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
integer
по умолчанию:1

Number of images, 1-10. Values of 11 or above return 400; 0 is silently treated as 1

Требуемый диапазон: 1 <= x <= 10
Пример:

1

aspect_ratio
enum<string>
по умолчанию:1:1

Output aspect ratio. Actual pixel dimensions per resolution tier:

Values outside this enum do not raise an error — they silently fall back to 1:1.

Доступные опции:
1:1,
16:9,
9:16,
4:3,
3:4
Пример:

"16:9"

resolution
enum<string>
по умолчанию:1k

Resolution tier. 1k is roughly 0.9-1.05 megapixels and returns JPEG; 2k is roughly 4.2-4.5 megapixels and returns PNG (5-6 MB per image). Both tiers cost the same.

4k returns 503; other invalid values (such as 1K or 1024x1024) silently fall back to 1k.

Доступные опции:
1k,
2k
Пример:

"1k"

response_format
enum<string>
по умолчанию:url

Response format. url returns a direct image link (no signed query params); b64_json returns a raw base64 string (without the data: prefix).

Invalid values silently fall back to the default url.

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

"url"

Ответ

Images generated successfully

created
integer

Creation timestamp. Always 0 for this model — do not use it for timing

Пример:

0

data
object[]

Array of image results, length equals the requested n

usage
object

Placeholder values — do not use for billing reconciliation. prompt_tokens is always 1000 x n, regardless of actual prompt length. Use the Console billing records instead.