Как использовать API генерации изображений по тексту Grok Image 2.0? Первое изображение за 5 минут

Как использовать API генерации изображений по тексту Grok Image 2.0? Три шага: POST /v1/tasks создаёт задачу, получив taskId, опрашивайте статус (или настройте callback), из data.output[0].url скачайте готовое изображение. $0.052 за изображение, 1K и 2K по одной цене.

Grok Image 2.0 уже доступен в HiAPI, откройте страницу модели и генерируйте сразу; новым пользователям при регистрации начисляется 200 кредитов — этого хватит на 1 изображение, чтобы оценить результат.

TL;DR

• Что это: grok-imagine-image-2.0/text-to-image — модель генерации изображений по тексту от xAI, работает через единый асинхронный интерфейс задач HiAPI.
• Сколько стоит: $0.052 за изображение; 1K / 2K, low / medium, любое соотношение сторон — одна цена; оплата за успешно сгенерированное изображение, при ошибке автоматический возврат. На $10 — около 192 изображений.
• Как вызвать быстрее всего: достаточно одного prompt; опционально три параметра: aspect_ratio, resolution, quality.

Какие параметры есть у генерации изображений по тексту Grok Image 2.0?

В input всего четыре поля:

Поле	Обязательно	Значения	Описание
prompt	Да	Строка	Описание изображения
aspect_ratio	Нет	1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 2:1, 1:2, 19.5:9, 9:19.5, 20:9, 9:20, auto	По умолчанию 1:1
resolution	Нет	1k, 2k	По умолчанию 1k
quality	Нет	low, medium	По умолчанию medium; medium — лучше детализация, low — быстрее

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

Два пути: онлайн-тест и API

Онлайн-тест (1 минута)

1. Откройте страницу модели генерации изображений по тексту и войдите.
2. Введите промпт, выберите соотношение сторон и разрешение.
3. Нажмите «Запустить», после успеха задачи просмотрите и скачайте изображение.

Подключение через API (5 минут)

1. Создайте API Key в консоли.
2. Отправьте задачу через POST /v1/tasks.
3. Опрашивайте GET /v1/tasks/<taskId> или настройте callback.
4. После успеха сразу скачайте data.output[0].url.

Product photography of a matte black ceramic coffee mug filled with steaming black coffee, thin wisps of steam curling upward, mug placed on a warm honey-toned wooden table near a bright window with sheer curtains, soft natural window light from the left creating gentle highlights on the mug's curved surface, shallow depth of field with the background softly blurred, plenty of empty negative space to the right of the mug for text overlay, warm cozy morning color grade, realistic commercial photography style, 3:2 aspect ratio

Сначала возьмите готовый рабочий промпт: ниже — продуктовое изображение 3:2, сгенерируйте с этим промптом → (выберите соотношение 3:2, разрешение 2K)

curl и Python: получаем первое изображение

Сначала задайте API Key:

export HIAPI_API_KEY="sk-..."

Все запросы передают Authorization: Bearer sk-<key>. Генерация изображений асинхронная и использует тот же интерфейс задач, что и другие модели HiAPI.

Шаг 1, создание задачи:

curl --fail-with-body -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0/text-to-image",
    "input": {
      "prompt": "A red apple on a wooden table, studio lighting, shallow depth of field",
      "aspect_ratio": "16:9",
      "resolution": "2k"
    }
  }'

Сразу возвращается taskId:

{
  "code": 200,
  "message": "success",
  "data": { "taskId": "tk-hiapi-01M01JGSGB818MX59GVZZCVH67" }
}

Шаг 2, опрос до конечного состояния:

curl --fail-with-body -sS https://api.hiapi.ai/v1/tasks/tk-hiapi-01M01JGSGB818MX59GVZZCVH67 \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Проверяйте data.status: success — успех, fail — ошибка; при остальных статусах продолжайте ожидание. Пример успешного ответа:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M01JGSGB818MX59GVZZCVH67",
    "status": "success",
    "storage": "temp",
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M01JGSGB818MX59GVZZCVH67-0.jpg",
        "artifactId": "76710",
        "expireAt": 1787364206
      }
    ]
  },
  "message": "success"
}

Обратите внимание на storage: "temp" и expireAt: адрес изображения временный, скачайте его сразу после завершения задачи или перенесите в собственное объектное хранилище.

Версия на Python:

Сначала установите requests (python3 -m pip install requests) и задайте HIAPI_API_KEY как выше. Скрипт опрашивает не более 10 минут; после тайм-аута сохраните taskId и продолжайте запросы.

import os
import time
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def task_data(response):
    response.raise_for_status()
    body = response.json()
    if body.get("code") != 200:
        raise RuntimeError(f"HiAPI request failed: {body}")
    return body["data"]


def generate_image(prompt: str, aspect_ratio: str = "1:1", resolution: str = "1k") -> str:
    create = requests.post(
        f"{BASE}/tasks",
        headers=HEADERS,
        json={
            "model": "grok-imagine-image-2.0/text-to-image",
            "input": {"prompt": prompt, "aspect_ratio": aspect_ratio, "resolution": resolution},
        },
        timeout=30,
    )
    task_id = task_data(create)["taskId"]
    print(f"taskId: {task_id}", flush=True)
    deadline = time.monotonic() + 600

    while time.monotonic() < deadline:
        poll = requests.get(f"{BASE}/tasks/{task_id}", headers=HEADERS, timeout=30)
        data = task_data(poll)
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {data}")
        time.sleep(2)
    raise TimeoutError(f"task {task_id} is still pending; query this ID instead of submitting again")


if __name__ == "__main__":
    url = generate_image("A red apple on a wooden table, studio lighting", resolution="2k")
    print(url)

На что обратить внимание перед запуском в продакшн?

• Для пакетной обработки используйте callback, а не плотный цикл опроса. При создании задачи передайте callback, и после завершения задачи HiAPI отправит уведомление на ваш адрес:

  {
    "model": "grok-imagine-image-2.0/text-to-image",
    "input": { "prompt": "..." },
    "callback": { "url": "https://your-service.example.com/hooks/hiapi", "when": "final" }
  }
  

  when: "final" уведомляет при переходе задачи в конечное состояние success или fail; получатель дедуплицирует по taskId. Для интерактивных страниц используйте опрос, для пакетной обработки — callback.

• Сразу переносите готовое изображение. data.output[0].url — временный адрес, он истекает по expireAt.

• Отправляйте задачу только один раз. После получения ответа сохраните соответствие taskId и бизнес-задачи; повторная отправка может создать несколько задач с отдельной оплатой. Если запрос на создание истёк по тайм-ауту и ID не получен, сначала проверьте записи задач, а затем решайте, отправлять ли повторно.

• Явно указывайте resolution. По умолчанию 1k; 1K и 2K по одной цене, для финальных изображений сразу передавайте "resolution": "2k".

• Для отладки промптов используйте quality: low. Та же цена, быстрее ответ; перед финалом переключитесь на medium.

• Обработка ошибок. Сначала проверяйте HTTP-статус и code, message в ответе, затем читайте data. При ошибках параметров или аутентификации исправьте их и отправьте повторно; если задача вернула fail, зафиксируйте ошибку и остановите опрос.

Похожие материалы

• Сколько стоит API Grok Image 2.0? Генерация изображений по тексту $0.052 за штуку, 2K без наценки
• Промпты для генерации изображений по тексту Grok Image 2.0: 5 сценариев, копируйте и генерируйте
• Подключение API генерации изображений по изображению Grok Image 2.0: изменение по одному референсному изображению
• Grok Image 2.0 vs GPT Image 2: сравнение на одинаковых промптах
• Аутентификация и быстрый старт

Частые вопросы

Как записывается ID модели? Пишите полностью grok-imagine-image-2.0/text-to-image, сохраняя номер версии 2.0 и /text-to-image.

Что делать при ошибке "additional properties not allowed"? input принимает только четыре поля: prompt, aspect_ratio, resolution, quality. Частые у других моделей size, n, seed, negative_prompt, output_format здесь недоступны — просто удалите их.

Можно ли получить несколько изображений за раз? Нет, каждая задача создаёт 1 изображение. Если нужно несколько, отправляйте несколько задач параллельно.

Сколько действует адрес результата? Это временное хранилище, expireAt в ответе — Unix-временная метка. Скачайте или перенесите изображение сразу после успеха задачи.

Нужно ли синхронно ждать результат? Нет. Интерфейс создания возвращает ответ сразу после постановки задачи в очередь; короткий скрипт опрашивает GET /v1/tasks/<taskId>, в продакшн-среде настройте callback.

Списываются ли деньги за неудачные задачи? Нет, оплата идёт за успешно сгенерированные изображения, при ошибке автоматический возврат. Когда data.status равен fail, остановите опрос.

Сгенерируйте первое изображение прямо сейчас

Сначала задайте HIAPI_API_KEY, создайте задачу через curl выше, затем запрашивайте по возвращённому data.taskId; после успеха скачайте из data.output[0].url. Хотите сначала посмотреть результат — откройте страницу модели генерации изображений по тексту: 200 кредитов за регистрацию хватит на 1 изображение.