Как использовать API преобразования текста в изображение grok-imagine-quality: curl, Python и один рабочий запрос

Краткое описание

• Что это: рабочий вариант использования grok-imagine-quality/text-to-image API на hiapi — создайте задачу через POST /v1/tasks, опрашивайте GET /v1/tasks/<taskId> (или используйте callback) и скачивайте изображение из output[0].url.
• Схема строгая и лаконичная: prompt (обязательный), aspect_ratio (13 соотношений, по умолчанию 1:1), resolution (1k | 2k, в нижнем регистре, по умолчанию 1k), output_format (jpeg | png | webp, по умолчанию jpeg). Любые другие поля будут отклонены с кодом 400.
• «Quality» — это класс, а не параметр настройки. Параметров quality или rich_detail не существует — более богатые детали, материалы и освещение этот вариант модели предоставляет по умолчанию. Если нужны дешёвые массовые черновики, на том же эндпоинте есть родственная модель стандартного класса grok-imagine/text-to-image.
• URL вывода имеет срок истечения expireAt — скачивайте вовремя или сохраняйте в постоянное хранилище.

Что вы создаёте и что нужно подготовить

Цель: отправить текстовый запрос (prompt) в grok-imagine-quality/text-to-image и получить готовый файл изображения, пригодный для главного визуала — сначала через curl, затем в виде небольшого Python-скрипта, который можно поместить в очередь задач.

Вам нужно только одно: ключ API hiapi. Получите его в консоли hiapi и экспортируйте:

export HIAPI_API_KEY="sk-..."

Каждый запрос аутентифицируется стандартным bearer-заголовком: Authorization: Bearer sk-<key>.

Минимальный рабочий запрос (curl)

Генерация изображений на hiapi доступна только асинхронно. Вам не нужно ждать длительного HTTP-вызова; вы создаёте задачу и получаете результат после её завершения.

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

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-quality/text-to-image",
    "input": {
      "prompt": "Главный визуал продукта: матовая чёрная эспрессо-машина на сланцевой столешнице, драматичный направленный свет, малая глубина резкости, премиальная коммерческая фактура",
      "aspect_ratio": "16:9",
      "resolution": "2k",
      "output_format": "png"
    }
  }'

Пока модель работает в фоне, вы сразу получаете taskId:

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

Шаг 2 — опрос до достижения терминального состояния:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Задача проходит через queued → handling → archiving и в итоге достигает success или fail. Только success содержит вывод:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "grok-imagine-quality/text-to-image",
    "status": "success",
    "created": 1783130400,
    "completed": 1783130460,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../image.png",
        "type": "image",
        "expireAt": 1783735260
      }
    ]
  }
}

Шаг 3 — скачивание до expireAt:

curl -o hero.png "https://cdn.hiapi.ai/tasks/.../image.png"

Тот же процесс на Python

Полный скрипт — создание, опрос, сохранение. Скопируйте, задайте HIAPI_API_KEY, запустите.

import os
import time

import requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

payload = {
    "model": "grok-imagine-quality/text-to-image",
    "input": {
        "prompt": (
            "Главный визуал продукта: матовая чёрная эспрессо-машина на сланцевой столешнице, "
            "драматичный направленный свет, малая глубина резкости, премиальная коммерческая фактура"
        ),
        "aspect_ratio": "16:9",
        "resolution": "2k",       # в нижнем регистре! "2K" будет отклонён с кодом 400
        "output_format": "png",
    },
}

resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
resp.raise_for_status()  # здесь 4xx = сам запрос отклонён
task_id = resp.json()["data"]["taskId"]
print("Задача создана:", task_id)

while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    status = task["status"]
    if status == "success":
        image = task["output"][0]
        with open("hero.png", "wb") as f:
            f.write(requests.get(image["url"], timeout=120).content)
        print("Сохранено hero.png")
        break
    if status == "fail":
        err = task["error"]
        raise RuntimeError(f"Задача завершилась ошибкой: {err['code']} {err['message']}")
    time.sleep(5)  # queued / handling / archiving — продолжаем опрос

Генерация в классе 2k обычно завершается за одну-две минуты; интервала опроса в 5 секунд достаточно.

Параметры, которые действительно существуют

Входная схема строгая — неизвестные поля завершаются ошибкой 400 INVALID_REQUEST: additional properties not allowed, а не игнорируются молча. Это хорошо: опечатки не просочатся в продакшен. Полный набор полей интерфейса:

Поле	Обязательно	Значения	По умолчанию
input.prompt	Да	Свободный текст	—
input.aspect_ratio	Нет	2:1, 20:9, 19.5:9, 16:9, 4:3, 3:2, 1:1, 2:3, 3:4, 9:16, 9:19.5, 9:20, 1:2	1:1
input.resolution	Нет	1k, 2k (только в нижнем регистре)	1k
input.output_format	Нет	jpeg, png, webp	jpeg

Перед тем как строить на этом, стоит знать три вещи:

• «quality» в названии — это класс, а не параметр.Вы можете встретить описание этой модели с более богатыми деталями, материалами и освещением — это сам вариант модели. Переключаемых полей rich_detail, quality или style нет.
• 1k и 2k тарифицируются по разным классам.Распространённый подход: итеративно дорабатывать prompt в 1k, а затем повторно запустить победивший prompt в 2k для финального материала. Актуальные цены за изображение см. на странице тарифов hiapi.
• Нет n, нет seed, нет negative_prompt.Одна задача создаёт одно изображение. Для вариантов отправляйте несколько задач параллельно — они независимы и ставятся в очередь одновременно.

Продакшен-замечания: callbacks, идемпотентность и ошибки

В продакшене предпочитайте callbacks вместо опроса.Передайте callback на верхнем уровне тела запроса (не внутри input), и hiapi вызовет ваш сервис, когда задача достигнет терминального состояния:

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

При when: "final" уведомления приходят и для success, и для fail, поэтому на своей стороне выполняйте дедупликацию по taskId. Оставьте низкочастотный опрос как резерв на случай потери callback — эндпоинт деталей задачи всегда остаётся источником истины.

Делайте повторы безопасными с помощью Idempotency-Key.При создании задачи принимается заголовок Idempotency-Key (до 255 байт). Повтор с тем же ключом никогда не создаст дублирующую задачу — воспроизведение вернёт исходный taskId:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Idempotency-Key: order-42-hero-image" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-imagine-quality/text-to-image", "input": {"prompt": "..."}}'

Различайте обработку трёх форм сбоя:

1. Ошибка аутентификации — HTTP 401 и {"error": {"code": "permission_denied", "type": "hiapi_error", ...}}. Проверьте ключ и есть ли у него права на эту модель; не повторяйте вслепую.
2. Неверный ввод — HTTP 400 и "error_code": "INVALID_REQUEST", сообщение указывает конкретное поле (например, resolution: value must be one of '1k', '2k'). Исправьте payload; повтор с тем же телом запроса снова завершится ошибкой.
3. Сбой на уровне задачи — вызов создания успешен, но задача завершилась со status: "fail" и объектом data.error. Проверьте error.code перед повторной отправкой.

Следите за expireAt.URL вывода временные. Скачайте файл сразу после успеха задачи или передайте storage: "persistent" при создании, чтобы сохранить вывод надолго.

Связанные страницы

• Страница модели grok-imagine-quality/text-to-image — песочница и тарифы по классам
• Полный справочник параметров в документации
• Справочник API создания задач — заголовки, идемпотентность, callbacks
• Как использовать grok-imagine-quality для imagem-to-image — тот же класс, редактирование существующих изображений
• Все модели изображений, видео и музыки

Часто задаваемые вопросы

В чём разница между grok-imagine-quality и grok-imagine/text-to-image? Тот же эндпоинт, та же структура запроса, другой класс. Класс quality ориентирован на главные визуалы и коммерческие материалы с более богатыми деталями и освещением, тарифицируется по разрешениям 1k/2k; стандартная версия grok-imagine/text-to-image — более быстрый и дешёвый вариант для массовых задач и набросков идей.

Почему "resolution": "2K" возвращает 400? Перечисление чувствительно к регистру и записывается в нижнем регистре: 1k или 2k. Значения в верхнем регистре отклоняются с INVALID_REQUEST.

Можно ли задать точные размеры в пикселях, например 1920x1080? Нет. Формой вы управляете через aspect_ratio (13 вариантов, от сверхширокого 2:1 до сверхвысокого 9:20), а чёткостью — через классы 1k/2k. У этой модели нет свободного поля size.

Можно ли сгенерировать несколько изображений в одном запросе? Нет — параметра n не существует. Отправляйте несколько задач параллельно; каждая задача возвращает собственный taskId и обрабатывается одновременно.

Поддерживает ли grok-imagine-quality изображение-в-изображение? Да, с отдельным id модели: grok-imagine-quality/image-to-image. Его схема описана в руководстве по изображение-в-изображение — она отличается от текста-в-изображение.

Сколько действует URL результата? Каждая запись output[] имеет Unix-время expireAt. Скачайте до этого срока или используйте storage: "persistent" при создании задачи (либо повысьте сохранность вывода позже), чтобы его сохранить.

Как выглядит задача, которая поставлена в очередь, но не завершена? GET /v1/tasks/<taskId> возвращает status равный queued, handling или archiving и пока не содержит output. Только success содержит скачиваемый вывод; fail содержит data.error.