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

Что grok-imagine/image-to-image даёт разработчикам

grok-imagine/image-to-image — это эндпоинт преобразования изображений: вы передаёте ему референсное изображение и промпт, а он возвращает новое изображение, которое следует промпту, оставаясь визуально связанным с референсом. Воспринимайте это как управляемую генерацию, а не генерацию с нуля. Модель, которую вы вызываете в HiAPI, имеет id grok-imagine/image-to-image, а всё остальное в запросе служит для описания желаемых изменений.

Выбирайте этот эндпоинт вместо вызова текст-в-изображение всякий раз, когда результат должен сохранить что-то из существующего материала — фотографию продукта с новой заменой фона, эскиз персонажа, который нужно отрендерить, композицию, требующую смены стиля. Текст-в-изображение подходит, когда у вас нет исходного изображения, а есть только описание; image-to-image — когда исходное изображение само является частью спецификации.

Поскольку HiAPI предоставляет это как единый унифицированный интерфейс, ваша интеграционная работа сводится к построению одной структуры запроса и обработке одной структуры ответа. Вам не нужно подключать отдельный SDK для каждого семейства моделей или заново изучать аутентификацию для каждого эндпоинта.

Анатомия запроса: модель, референсное изображение и промпт

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

Id модели

Поле model содержит строку grok-imagine/image-to-image. Рассматривайте её как константу в клиенте, а не как жёстко закодированный литерал, разбросанный по всей кодовой базе — если позже вы захотите опробовать другие модели HiAPI, вам понадобится единственное место для изменения.

Референсное изображение

Референсное изображение — это якорь. Способ его передачи зависит от выбранного транспорта: это может быть URL, который API может загрузить, или встроенные base64-данные, подходящие для изображений, сгенерированных на лету или недоступных из публичной сети. Для материалов, которые вы уже разместили, предпочитайте URL; для пользовательских загрузок, ещё не сохранённых нигде публично, предпочитайте встроенные данные. В любом случае проверьте изображение перед отправкой: поддерживаемый формат, ненулевой размер, достаточные размеры.

Промпт

Промпт описывает преобразование, а не всю сцену. Если референсное изображение уже содержит субъект, опишите то, что должно измениться — стиль, освещение, фон, материал — а неизменное оставьте подразумеваемым. Чрезмерное указание того, что уже видно на референсе, часто конфликтует с обусловливанием по изображению, а не помогает.

Обработка соотношения сторон

Оставшаяся часть — как определяется размер вывода; это тема следующего раздела. Разделите эти четыре части в коде построения запроса, чтобы каждую можно было независимо проверять и логировать.

Использование опции auto aspect

Опция auto aspect позволяет API выбирать размер вывода вместо того, чтобы вы фиксировали явную ширину и высоту. При включении сервис выводит подходящее соотношение сторон из контекста запроса — прежде всего из референсного изображения, — благодаря чему форма вывода оказывается более осмысленной относительно вашего ввода, а не втискивается в формат по умолчанию.

Это важнее, чем кажется. Если вы фиксируете размеры, не соответствующие пропорциям референсного изображения, вы получите артефакты вроде почтового ящика, неудобную обрезку субъекта или композицию, игнорирующую кадрирование исходника. auto aspect избегает таких несоответствий, заставляя геометрию следовать за вводом.

Когда оставлять auto включённым

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

Когда явно фиксировать размеры

• У вас фиксированные слоты в UI или цели печати, требующие точной геометрии вывода.
• Вы генерируете пакет изображений, которые должны быть визуально согласованы по размеру.

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

Рабочий запрос curl

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

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/image-to-image",
    "prompt": "<describe the transformation you want>",
    "image": "<publicly reachable URL of your reference image>",
    "aspect_ratio": "auto"
  }'

Заполнители, которые нужно заменить

• $HIAPI_API_KEY — читайте ключ из переменной окружения, а не вставляйте его в команду. Если переменная не задана, запрос завершится ошибкой аутентификации, а ключ никогда не попадёт в историю вашей оболочки.
• <describe the transformation you want> — краткая, конкретная инструкция, например изменение стиля или фона.
• <publicly reachable URL of your reference image> — URL, который сервис может загрузить без аутентификации. Если ваши материалы приватны, используйте встроенные base64-данные.

Чтение ответа

При первом запуске пропустите вывод через средство форматирования JSON, чтобы ясно видеть структуру ответа. Обратите внимание на две вещи: полезную нагрузку изображения (в зависимости от режима ответа это может быть URL или закодированные данные) и идентификатор задачи, если вызов обрабатывается асинхронно. Во время разработки сохраняйте полный исходный ответ в логах — когда что-то выглядит не так, это самый быстрый способ ответить на вопрос «что на самом деле вернулось».

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

Версия на Python должна соответствовать curl-запросу поле за полем. Ценность поддержания их согласованности в том, что баг, воспроизведённый в одной версии, можно подтвердить в другой, не гадая о переводе.

import os
import requests

API_URL = "https://api.hiapi.ai/v1/images/generations"
MODEL = "grok-imagine/image-to-image"

def generate_from_reference(prompt: str, image_url: str) -> dict:
    payload = {
        "model": MODEL,
        "prompt": prompt,
        "image": image_url,
        "aspect_ratio": "auto",
    }
    response = requests.post(
        API_URL,
        headers={
            "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=120,
    )
    response.raise_for_status()
    return response.json()

Где должна находиться обработка ошибок

Оборачивайте вызов, а не вызывающую сторону. response.raise_for_status() преобразует не-2xx ответы в исключения, поэтому один try/except вокруг generate_from_reference охватывает как сбои транспорта, так и отказы API. Если вы хотите структурированное логирование причин сбоя, проверьте response.status_code и тело ошибки внутри функции до выброса исключения.

Держите клиент чистым

Считывайте API-ключ один раз при запуске, задавайте явный таймаут и возвращайте разобранный JSON, а не необработанный объект ответа. Вызывающей стороне не нужно знать детали HTTP. В тестах направьте API_URL на заглушечный сервер, чтобы проверять логику построения запроса без затрат на реальные вызовы генерации.

Синхронные и асинхронные ответы

Некоторые запросы image-to-image завершаются достаточно быстро, чтобы вернуть результат в том же HTTP-ответе. Другие обрабатываются как задачи: первоначальный вызов возвращает идентификатор, а изображение становится доступным позже. Ваш клиент не должен предполагать ни один из вариантов.

Как их различить

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

Структурируйте код для обоих случаев

Небольшая функция-диспетчер держит оба пути вне бизнес-логики:

def resolve_result(response_json: dict) -> dict:
    if "image" in response_json or "data" in response_json:
        return response_json
    job_id = response_json.get("id") or response_json.get("job_id")
    if job_id:
        return poll_until_done(job_id)
    raise RuntimeError(f"Unrecognized response shape: {response_json}")

Правила опроса, помогающие избежать проблем

• Используйте экспоненциальную задержку с верхним пределом, а не плотный цикл.
• Задайте максимальное общее время ожидания и корректно завершайтесь с ошибкой при его превышении.
• Рассматривайте каждое нетерминальное состояние как «продолжать ждать»; терминальных состояний только два: успех и сбой.
• Логируйте id задания при каждом опросе, чтобы зависшее задание можно было отследить только по логам.

Диспетчер означает, что при переключении между синхронным и асинхронным поведением код, вызывающий resolve_result, никогда не нужно менять.

Отладка распространённых кодов ошибок

Большинство неудачных вызовов этого эндпоинта попадают в несколько категорий. Проверяйте по следующему списку по порядку — он идёт от самой частой причины к самой редкой.

Сбой аутентификации

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

Ошибки валидации референсного изображения

Отказ, связанный с изображением, обычно означает одно из четырёх: URL недоступен публично, формат не поддерживается, полезная нагрузка слишком велика или изображение слишком маленькое либо повреждено. Проверьте URL в браузере без учётных данных — если там он не загружается, API тоже не сможет его загрузить. Для встроенного base64 убедитесь, что кодировка — чистый base64 и без префикса data-URL (если параметр не предполагает его).

Ошибки промпта и параметров

Пустой или слишком большой промпт либо неизвестное значение параметра дают ответ валидации. Логируйте точную отправленную полезную нагрузку вместе с ошибкой — значительная часть сбоев вызвана опечатками в именах полей, а не в значениях.

Ограничение частоты

Ответ об ограничении частоты означает задержку, а не немедленный повтор. Следуйте указаниям о повторной попытке из заголовков ответа, добавляйте джиттер и ограничивайте число повторов. Повторы без задержки превращают временное ограничение в постоянное.

Ошибки на стороне сервера

5xx-ответы относятся к серверной стороне. Повторяйте ограниченное число раз с задержкой; если проблема сохраняется, зафиксируйте id запроса и отметку времени из ответа и снизьте параллелизм на время расследования.

Чек-лист перед запуском в продакшен

Рабочий запрос — это начало, а не конец. Прежде чем этот эндпоинт будет обрабатывать реальный трафик, убедитесь в следующем.

Проверяйте входные данные на границе

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

Повторяйте только безопасные для повтора запросы

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

Логируйте достаточно, чтобы восстановить сбой

Логируйте id модели, хеш или усечённую форму промпта, идентификатор референсного изображения (не полную нагрузку), статус ответа, id задания (если есть) и id запроса. Этого набора обычно достаточно, чтобы ответить на вопрос «что произошло», не сохраняя конфиденциальное содержимое.

Держите ключи вне кода

Считывайте API-ключ из окружения или менеджера секретов, никогда из литерала в исходном коде. Регулярно меняйте ключи и немедленно отзывайте при подозрении на утечку.

Следите за затратами

Биллинг этого эндпоинта определяется генерациями, поэтому ключевые рычаги — объём запросов, повторы и частота опроса. Избегайте штормов повторов, применяйте задержку при опросе и кэшируйте результаты по промпту и референсному изображению для сценариев, где один и тот же запрос повторяется. Смотрите панель тарифов HiAPI для актуальных расценок, а не полагайтесь на жёстко закодированные предположения.

Тестируйте неудачные пути

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

С построением запроса, диспетчеризацией ответов и обработкой ошибок grok-imagine/image-to-image станет обычной частью вашего конвейера, а не особым случаем.