HiAPI
Блог

Руководство

Как использовать grok-imagine/text-to-image через HiAPI API: руководство по curl и Python

Nov 12, 2026
Многослойная бумажная обложка в кремовых и графитовых тонах с единственным терракотовым листом, выступающим на небольшой глубине.
На этой странице

Что даёт вам grok-imagine/text-to-image

grok-imagine/text-to-image — это эндпоинт генерации изображений по тексту, доступный через HiAPI: вы отправляете подсказку и несколько параметров генерации в формате JSON по HTTP и получаете изображение. Вот и весь контракт. Не нужно устанавливать SDK, инициализировать сессию или опрашивать фоновые задачи, чтобы увидеть первое изображение.

Его место в рабочем процессе разработчика:

  • Прототипирование. Вы можете пройти путь от идеи до отрендеренного изображения одной командой в терминале, что позволяет быстро тестировать идеи для подсказок.
  • Контентные конвейеры. Поскольку это обычный HTTP-вызов, вы можете вызывать его из бэкенд-сервиса, воркера очереди или скрипта сборки так же, как любой другой API.
  • Продуктовые функции. Генерация изображений для пользователей обычно означает необходимость предсказуемой обработки запросов/ответов, структурированных ошибок и повторов. Эндпоинт без сохранения состояния отлично подходит для всех трёх пунктов.

Чем этот эндпоинт не является: он не хранит подсказки за вас, не управляет библиотекой сгенерированных изображений и не заменяет вашу собственную оркестрацию. Запрос — на вас, вывод — на вас, и куда деваются байты — тоже на вас.

Это руководство сосредоточено на том, чтобы сначала заставить запрос работать, а затем сделать его надёжным. Независимо от того, вызываете ли вы через curl или Python, шаблон полностью одинаков, поскольку оба варианта — это один и тот же HTTP-запрос с аутентификацией. Начните с минимального рабочего варианта, убедитесь, что обмен данными прошёл успешно, а затем добавляйте сложность.

Предварительные требования и аутентификация

Перед первым вызовом убедитесь, что у вас есть следующее:

  1. Аккаунт HiAPI и API-ключ. Относитесь к ключу как к секрету: загружайте его из переменной окружения и никогда не хардкодьте в скрипты, которые могут быть закоммичены.
  2. Инструмент для отправки HTTP-запросов. Для первого теста достаточно curl. Для Python используйте requests или httpx; оба рассматриваются ниже.
  3. Сетевой доступ к хосту HiAPI API. Если вы за корпоративным прокси, убедитесь, что для вашей оболочки задан HTTPS_PROXY, чтобы его могли прочитать и curl, и Python.

Ключ передаётся как bearer-токен через заголовок Authorization:

export HIAPI_API_KEY="your-key-here"

Затем каждый запрос несёт:

Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

Две привычки, которые стоит завести сразу:

  • Не допускайте попадания ключа в URL. Ни одна часть запроса не должна содержать учётные данные в строке запроса, поскольку они в конечном итоге попадают в логи и историю оболочки.
  • Используйте отдельный ключ для каждого окружения. Ключи для разработки и продакшена должны быть разными значениями, чтобы вы могли ротировать один, не затрагивая другой.

Если вы ещё не создали ключ, создайте его в панели управления HiAPI и сохраните в вашем менеджере секретов или в локальном файле .env, исключённом из системы контроля версий. Как только echo $HIAPI_API_KEY выведет значение, вы готовы отправить первый запрос.

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

Самый маленький полезный вызов отправляет только идентификатор модели и подсказку. Всё остальное имеет значения по умолчанию, поэтому не спешите настраивать параметры, пока не увидите возвращённое изображение.

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/text-to-image",
    "prompt": "маяк на скалистом побережье в сумерках, спокойное море, мягкий пасмурный свет"
  }'

Что делает каждая часть:

  • -X POST с JSON-телом запроса — стандартная форма для эндпоинта генерации.
  • model явно выбирает grok-imagine/text-to-image. Фиксируйте имя модели в скриптах, а не полагайтесь на значения по умолчанию, чтобы изменения значений по умолчанию не меняли молча ваш вывод.
  • prompt — единственный содержательный вход. Для первого теста держите его в виде одного чёткого предложения.

Успешный ответ вернёт JSON с сгенерированным изображением, обычно это URL или base64-полезная нагрузка, в зависимости от запрошенного формата ответа. Прежде чем писать код разбора, прочитайте ответ с помощью инструмента форматирования JSON. Если вы смотрите вывод в терминале, передача через python -m json.tool сделает структуру более читаемой.

После успешного запуска сохраните исходный ответ в файл, чтобы у вас был заведомо рабочий базовый пример:

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json \
  -o response.json

Поместив тело запроса в request.json, вы сможете редактировать подсказку, не борясь с кавычками оболочки, что особенно важно, когда подсказка становится длиннее или содержит знаки препинания.

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

Версия на Python — это тот же HTTP-вызов, только с более удобным опытом: словарь вместо вложенных кавычек и прямая работа с байтами изображения.

import os
import requests

api_key = os.environ["HIAPI_API_KEY"]
base_url = os.environ["HIAPI_BASE_URL"]

payload = {
    "model": "grok-imagine/text-to-image",
    "prompt": "маяк на скалистом побережье в сумерках, спокойное море, мягкий пасмурный свет",
}

response = requests.post(
    f"{base_url}/v1/images/generations",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)
response.raise_for_status()
data = response.json()
print(data)

Два момента заслуживают особого упоминания. Во-первых, timeout=120 — генерация изображений не мгновенна, и запрос без таймаута будет бесконечно висеть в воркере, если upstream зависнет. Во-вторых, вызывайте raise_for_status() перед разбором, чтобы тело ответа с ошибкой не было ошибочно принято за успешный ответ с изображением.

Чтобы сохранить изображение, обработайте обе формы ответа:

item = data["data"][0]

if item.get("b64_json"):
    import base64
    image_bytes = base64.b64decode(item["b64_json"])
else:
    image_bytes = requests.get(item["url"], timeout=60).content

with open("output.png", "wb") as f:
    f.write(image_bytes)

Если вы предпочитаете единый набор зависимостей, httpx используется так же — httpx.post(..., json=payload). Ключевой момент в том, что тело запроса и заголовки полностью совпадают с примером на curl — именно эта согласованность делает оба примера взаимозаменяемыми и делает отладку предсказуемой.

Структурирование подсказок под соотношение сторон

Широкоформатный вывод терпит неудачу определённым образом: у модели много горизонтального пространства для заполнения, поэтому она либо повторяет элементы, либо оставляет крошечный субъект плавать в пустом кадре. Решайте это структурой подсказки, а не нагромождением дополнительных прилагательных.

Используйте трёхчастный каркас:

  1. Субъект — о чём изображение, укажите первым и конкретно. «Грузовое судно, входящее в порт» лучше, чем «корабль».
  2. Стиль — язык рендеринга: фотография, плоская векторная графика, акварель, кинокадр. Достаточно одного-двух слов.
  3. Композиция — как организован кадр; здесь решается судьба широкоформатного соотношения.

Для композиции явно называйте горизонтальную структуру:

  • Указывайте порядок чтения слева направо или панорамный: «широкий план, субъект в правой трети, слева открытое небо».
  • Описывайте передний план, средний план и фон как отдельные полосы, поскольку широкоформатный кадр естественно читается слоями.
  • Явно указывайте, чем заполнены края: «портовые краны слева, открытая вода справа». Края — первое место, где широкоформатное изображение становится пустым.
  • Избегайте подсказок, подразумевающих портретную или квадратную композицию — крупных планов лиц, одиночных центрированных объектов — и ожидайте, что их растянут или добавят чёрные полосы.

Когда вы задаёте параметр соотношения сторон для панорамного формата, меняйте и подсказку. Подсказка, написанная для квадратного кадра, породит квадратную концепцию на широком холсте. Перепишите её, включив горизонтальную протяжённость: горизонт, улицу, ряды объектов, группу, рассредоточенную по комнате.

Меняйте по одной переменной за раз. Зафиксируйте соотношение сторон и измените формулировку; затем зафиксируйте формулировку и измените пропорции. Записывайте оба изменения вместе с выводом, чтобы вы могли судить, какое изменение действительно помогло.

Обработка ошибок и кодов ответа

Сначала читайте код состояния, затем тело ответа. Каждый распространённый сбой указывает на свой способ исправления, и их смешение ведёт к потере времени.

401 Unauthorized

Ключ отсутствует, имеет неверный формат или отозван. Проверьте, что заголовок в точности Authorization: Bearer <key>, что переменная окружения действительно раскрылась (выведите её длину, а не значение), и что вы не отправили по ошибке ключ из другого окружения.

400 Bad Request

Ваш JSON корректен для HTTP, но недопустим для этого эндпоинта. Частые подозреваемые:

  • model содержит опечатку или отсутствует. Должно быть grok-imagine/text-to-image.
  • prompt пуст или отсутствует.
  • Какой-то параметр имеет неверный тип — строка там, где должно быть число, или наоборот.
  • Тело запроса вообще не является валидным JSON, обычно из-за проблем с кавычками оболочки в curl. Переместите тело запроса в файл и используйте -d @request.json.

Прочитайте тело сообщения об ошибке; обычно оно указывает на проблемное поле.

429 Too Many Requests

Вы отправляете запросы быстрее квоты. Исправление на стороне клиента: экспоненциальная задержка, очередь, повтор. Не ужесточайте цикл повторов из-за получения 429 — это сделает ситуацию хуже.

5xx Server Errors

Это временные или вышестоящие условия. Повторите с задержкой, а если сбой сохраняется после нескольких попыток, зафиксируйте нагрузку запроса и тело ответа для диагностики, а не повторяйте бесконечно.

Таймауты и ошибки соединения

Это вовсе не коды состояния HTTP, но на практике самые частые сбои. Если requests выдаёт таймаут соединения, запрос мог всё равно быть обработан. Прежде чем писать цикл повторов, решите для своего случая, означает ли таймаут «повторить» или «отказаться».

Настройка и повторы в продакшене

После того как базовый запрос работает, настраивайте маленькими шагами: сначала измените формулировку подсказки, затем соотношение сторон, затем другие параметры, сравнивая вывод бок о бок. Сохраняйте каждую нагрузку запроса вместе с её выводом, чтобы результаты всегда были воспроизводимы.

Продакшен-обёртка делает три вещи: повторяет только те сбои, которые стоит повторять, записывает достаточно логов для отладки и громко падает, когда сдаётся.

import time
import requests

def generate(payload, max_attempts=4):
    for attempt in range(1, max_attempts + 1):
        try:
            r = requests.post(
                f"{base_url}/v1/images/generations",
                headers=headers,
                json=payload,
                timeout=120,
            )
        except requests.RequestException as exc:
            log.warning("request failed attempt=%d err=%s", attempt, exc)
            time.sleep(2 ** attempt)
            continue

        if r.status_code == 429 or r.status_code >= 500:
            log.warning("retryable status=%d attempt=%d", r.status_code, attempt)
            time.sleep(2 ** attempt)
            continue

        if r.status_code >= 400:
            raise RuntimeError(f"{r.status_code}: {r.text[:500]}")

        return r.json()

    raise RuntimeError("exhausted retries")

Замечания об этом шаблоне:

  • Экспоненциальная задержка с верхним пределом (2 ** attempt) не даёт клиенту, ограниченному по частоте, снова и снова бить по эндпоинту. Если вы запускаете много воркеров, добавьте джиттер.
  • Повторяйте только 429, 5xx и сетевые ошибки. 400 или 401 будут падать одинаково при каждой попытке.
  • Логируйте номер попытки и статус, но не API-ключ, и никогда не логируйте полную подсказку, если она может содержать пользовательские данные.
  • Ограничьте общее время. Цикл повторов без ограничения превратит медленный запрос в зависший воркер.

Измеряйте свою задержку и частоту успеха, а не предполагайте их; эти два числа говорят вам, нужно ли больше параллелизма или больше задержек. Начните с минимального запроса из этого руководства, оберните его приведённым выше вспомогательным кодом, а затем итерируйтесь оттуда.

Похожие статьи

Все статьи →

Начните работать с постоянными артефактами ИИ

Получите API-ключ и вызывайте модели изображений, видео и аудио через один API на основе tasks.

Читать документацию API