Skip to main content
POST
Text-to-image: generate images from a text prompt
Интерактивный Playground справа позволяет напрямую протестировать эндпоинт. Введите ваш API-ключ в Authorization (формат: Bearer sk-xxx), заполните prompt, выберите aspect_ratio / resolution и отправьте.
Когда использовать эту страницу: генерация изображений по одному лишь prompt — без загрузки изображения. Чтобы изменить существующее изображение или объединить несколько, используйте эндпоинт редактирования изображений.
⚠️ Не отправляйте в этот эндпоинт reference imagesПередача 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 секунд, поэтому установите timeout клиента на 360 секунд — см. Лучшие практики 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.