Skip to main content
POST
Text-to-image: generate images from a text prompt
🔒 По умолчанию не открыт: Grok Imagine 2 не входит в группу Default. Он находится в собственной группе Grok_imagine, и перед вызовом необходимо запросить доступ к нему (включая 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 — референс молча отбрасывается, а тарификация всё равно выполняется.При отсутствии сигнала об ошибке это обычно обнаруживается только тогда, когда кто-то замечает, что результат не имеет ничего общего с входными данными. Любой workflow с референсным изображением должен использовать /v1/images/edits.
⚠️ Недопустимые параметры не вызывают ошибокНедопустимые aspect_ratio (например, 5:7), resolution (например, 1K, 1024x1024) и response_format (например, base64) все молча заменяются значениями по умолчанию и всё равно возвращают изображение. Если результат не соответствует ожиданиям, сначала проверьте написание параметров — обратите внимание, что значения resolution указываются в нижнем регистре: 1k / 2k.Одно исключение: resolution: "4k" возвращает 503 model_service_unavailable, что означает тарифный уровень не поддерживается, а не то, что канал недоступен. Повторная попытка не поможет.
Все API изображений являются синхронными: асинхронного ID задачи нет, поэтому при отключении клиента результат теряется, хотя запрос всё равно тарифицируется. 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.