Как вызывать muse-image-1.0/text-to-image через HiAPI API: curl и Python

Что на самом деле представляет собой эта интеграция

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

Задействовано немного компонентов:

• Ваш API-ключ — аутентифицирует запрос через заголовок Authorization.
• Конечная точка — фиксированный URL-путь muse-image-1.0/text-to-image на базовом URL HiAPI.
• JSON-тело запроса — содержит ваш промпт и любые необязательные параметры, которые принимает модель.
• Тело ответа — возвращает данные сгенерированного изображения, которые вы декодируете или перенаправляете.

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

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

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

1. API-ключ из панели управления вашего аккаунта HiAPI. Обращайтесь с ним как с паролем; никогда не коммитьте его в систему контроля версий.
2. HTTP-клиент — для тестирования подойдёт curl; целевая среда для скриптовой версии — Python 3.8+.
3. Базовый URL API HiAPI, который вы можете найти в документации панели управления вместе с ключом.

Аутентификация использует Bearer-токен в заголовке Authorization. Он нужен для каждого запроса к muse-image-1.0/text-to-image:

Authorization: Bearer $HIAPI_API_KEY

Храните ключ в переменной окружения, а не жёстко зашивайте в скрипт:

export HIAPI_API_KEY="your-key-here"

Путь конечной точки этой модели — /muse-image-1.0/text-to-image, добавляемый после базового URL. Точный базовый URL указан в вашей панели управления HiAPI; также сохраните его в переменной окружения, чтобы можно было переключать окружения без изменения кода:

export HIAPI_BASE_URL="https://api.hiapi.ai"   # confirm the current value in your dashboard

После настройки этих двух переменных вы готовы отправлять запросы.

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

Ниже минимальный вызов muse-image-1.0/text-to-image. Он отправляет промпт и записывает исходный JSON-ответ в файл, чтобы вы могли его проверить перед написанием кода разбора.

curl -sS -X POST "$HIAPI_BASE_URL/muse-image-1.0/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a quiet harbor at dawn, soft fog, wide angle",
    "n": 1
  }' \
  -o response.json

Несколько замечаний о теле запроса:

• prompt обязателен — это текстовое описание, которое отрисовывает модель.
• n необязателен и управляет количеством запрашиваемых изображений. Если его опустить, принимается значение по умолчанию.
• Включайте только параметры, которые вы подтвердили в справочной документации HiAPI API для этой модели. Не угадывайте недокументированные поля; неизвестные параметры могут быть отклонены проверкой сервера или молча проигнорированы.

При успешном запросе response.json содержит данные изображения. При ошибке вы получите тело ответа с ошибкой и код состояния, отличный от 2xx — см. раздел об обработке ошибок ниже.

Вы можете проверить HTTP-код состояния, не выводя всё тело ответа:

curl -sS -o /dev/null -w "%{http_code}\n" -X POST "$HIAPI_BASE_URL/muse-image-1.0/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"test"}'

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

Python-версия использует requests и полностью идентична curl-вызову — та же конечная точка, те же заголовки, то же тело. Выделите её в переиспользуемую функцию.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]

def generate_image(prompt: str, n: int = 1) -> dict:
    url = f"{BASE_URL}/muse-image-1.0/text-to-image"
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }
    payload = {"prompt": prompt, "n": n}

    response = requests.post(url, headers=headers, json=payload, timeout=60)
    response.raise_for_status()  # raise on 4xx/5xx
    return response.json()

if __name__ == "__main__":
    result = generate_image("a quiet harbor at dawn, soft fog, wide angle")
    print(result.keys())

Две детали стоит сохранить:

• timeout=60 — задайте явный тайм-аут. Генерация изображений медленнее типичного вызова JSON API; без тайм-аута ваш процесс может зависнуть на неопределённое время при застрявшем соединении.
• raise_for_status() — делает HTTP-ошибки исключениями, а не позволяет вам молча парсить тело ответа с ошибкой как изображение.

Если вы уже используете httpx или aiohttp, переход прост: те же заголовки, то же JSON-тело. Этот запрос не зависит от конкретной HTTP-библиотеки.

Чтение синхронного ответа

Поскольку muse-image-1.0/text-to-image синхронен, данные изображения приходят в том же ответе — второй вызов для получения результата не нужен. Ответ — это JSON; перед написанием парсера один раз проверьте его структуру:

import json

result = generate_image("a quiet harbor at dawn")
print(json.dumps(result, indent=2)[:500])

То, как обрабатывать изображение, зависит от того, что несёт ответ:

Если ответ содержит данные изображения в base64

Декодируйте строку и запишите байты в файл:

import base64

b64 = result["data"][0]["b64_json"]   # field name: confirm against the API reference
with open("output.png", "wb") as f:
    f.write(base64.b64decode(b64))

Если ответ содержит URL

Скачайте его обычным GET-запросом — этот URL уже авторизован для получения, поэтому не прикрепляйте API-ключ к стороннему хосту:

import requests

image_url = result["data"][0]["url"]   # field name: confirm against the API reference
img = requests.get(image_url, timeout=60)
img.raise_for_status()
with open("output.png", "wb") as f:
    f.write(img.content)

Точные имена полей — b64_json и url, а также внешняя структура, которая их оборачивает, — определены в справочной документации HiAPI API для этой модели. Один раз выведите ответ, чтобы подтвердить структуру, затем пишите код под неё. Не предполагайте структуру других моделей.

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

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

HiAPI возвращает стандартные HTTP-коды состояния. Полезное правило сортировки: если я снова отправлю тот же запрос, не меняя его, сможет ли он успешно выполниться?

Исправьте запрос — не повторяйте

• 400 Bad Request — некорректный JSON или параметры, которые модель не принимает. Проверьте, присутствует ли prompt, и не выдумали ли вы поля. Исправьте тело запроса; повторная отправка как есть снова не удастся.
• 401 Unauthorized — отсутствующий или неверный API-ключ. Убедитесь, что HIAPI_API_KEY задан и не был ротирован.
• 403 Forbidden — ключ действителен, но нет доступа к этой конечной точке. Проверьте права доступа вашего аккаунта в панели управления.
• 404 Not Found — неверный путь. Убедитесь, что строка конечной точки ровно /muse-image-1.0/text-to-image, а базовый URL верен.
• 422 Unprocessable Entity — JSON корректен, но семантически неверен, например, значение вне допустимого диапазона. Прочитайте сообщение об ошибке; оно обычно указывает имя поля.

Повтор с задержкой

• 429 Too Many Requests — вы ограничены по частоте. Примените экспоненциальную задержку и повторите; если есть заголовок Retry-After, соблюдайте его.
• Ошибки 5xx — сбой на стороне сервера. Повторяйте с экспоненциальной задержкой и пределом (например, три попытки), затем прекратите и покажите ошибку.

Компактный цикл повторных попыток:

import time

def post_with_retry(url, headers, payload, attempts=3):
    for i in range(attempts):
        resp = requests.post(url, headers=headers, json=payload, timeout=60)
        if resp.status_code == 429 or resp.status_code >= 500:
            time.sleep(2 ** i)
            continue
        resp.raise_for_status()
        return resp.json()
    raise RuntimeError(f"failed after {attempts} attempts: {resp.status_code} {resp.text}")

Всегда записывайте код состояния и тело ответа с ошибкой при сбое. Сообщение в теле ответа подскажет, к какой из двух категорий относится данная ошибка.

Производственный чек-лист перед выпуском

Несколько привычек помогут вызовам muse-image-1.0/text-to-image оставаться предсказуемыми после того, как они покинут ваш ноутбук:

• Зафиксируйте структуру запроса. Проверяйте JSON-тело по полям, задокументированным в справочной документации API. Если добавляете параметр, сначала убедитесь, что он поддерживается.
• Задавайте тайм-ауты везде. Вызовы генерации и любые загрузки возвращаемых данных изображения нуждаются в явных тайм-аутах.
• Различайте категории ошибок. Отделяйте повторяемые (429, 5xx) от окончательных (400, 401, 403, 404, 422) сбоев, чтобы ваши оповещения не были шумными, а повторы не тратились впустую.
• Логируйте ключевую информацию. Если ответ предоставляет ID запроса, логируйте его, код состояния, задержку и длину промпта — но не сам промпт, если он может содержать конфиденциальный текст.
• Следите за факторами затрат. Генерация тарифицируется по выходу — количество изображений, размеры и частота повторных попыток влияют на стоимость. Избегайте повторов окончательных ошибок и повторной генерации, когда кэширование результатов целесообразно.
• Держите ключи на сервере. Никогда не встраивайте API-ключ в браузер или мобильный клиент для прямых вызовов конечной точки.

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