HiAPI
Блог

Руководство

Как вызывать flux-3-image-klein через HiAPI API: curl, Python и рабочие примеры запросов

Практическое руководство по интеграции для разработчиков: от первого запроса до надёжных пакетных вызовов

Nov 12, 2026
Почти чёрная обложка с полем мятно-зелёных точек, плотность которых возрастает слева направо, а по краю рассыпаются бирюзовые точки.
Модель
flux-3-image-klein
На этой странице

Реальные требования к интеграции flux-3-image-klein

Прежде чем писать первую строку кода, разберитесь, сколько звеньев отделяет ваш скрипт от сгенерированной картинки. Для flux-3-image-klein на HiAPI этот список короткий: одна конечная точка, одни учётные данные, одно JSON-тело запроса и один объект ответа, который нужно разобрать.

Вот мысленная модель, которую стоит держать в голове:

  • Конечная точка — один маршрут HiAPI обслуживает генерацию изображений этой моделью. Все запросы идут туда; модель указывается в теле запроса, а не различается по URL.
  • Учётные данные — API-ключ, выданный вашей учётной записью HiAPI. Он передаётся в HTTP-заголовке при каждом вызове. Обращайтесь с ним как с паролем: читайте из переменной окружения и никогда не вписывайте в файлы, которые могут быть закоммичены.
  • Тело запроса — небольшой JSON-объект, описывающий модель, промпт и несколько необязательных параметров, влияющих на вывод (размер, подсказки стиля и т. п.).
  • Ответ — JSON-объект, после разбора которого вы получаете ссылку на сгенерированное изображение и метаданные, возвращаемые API.

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

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

Первый рабочий запрос через curl

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

Сначала экспортируйте ключ, чтобы он никогда не появлялся в истории оболочки в виде литерала:

export HIAPI_API_KEY="your-api-key-here"
export HIAPI_BASE_URL="https://api.hiapi.ai"

Затем отправьте минимальный запрос:

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

Замечание об URL: точный базовый путь и маршрут определяются документацией HiAPI — используйте конечную точку из документации и не копируйте имя хоста из сторонних скриншотов. Задайте HIAPI_BASE_URL в окружении один раз, и каждый последующий пример будет его переиспользовать.

Теперь посмотрите, что делает каждое поле:

  • model указывает, какая модель обрабатывает задачу. Обязательно совпадайте с документацией; опечатка здесь — самая частая причина запросов, которые выглядят корректными, но не возвращают полезного результата.
  • prompt — ваше описание на естественном языке. Конкретно описывайте объект, композицию, освещение и атмосферу — модель откликается на описательные детали, а расплывчатые промпты дают непредсказуемый результат, который невозможно отладить.
  • Заголовки обязательны: bearer-токен выполняет аутентификацию, а Content-Type: application/json сообщает серверу, как разбирать тело запроса.

При успехе вы получите JSON-ответ, содержащий ссылку на сгенерированное изображение (обычно URL или размещённый ресурс) и метаданные. Если хотите проверить и заголовки ответа, сначала выполните curl без подавления -sS, чтобы увидеть полный ответ, разберитесь в структуре и затем сужайте вывод. Сохраните один реальный ответ в файл — он пригодится как тестовая фикстура, когда будете писать и тестировать Python-клиент.

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

Перенос запроса в Python

Когда curl работает, переносите в Python, не меняя семантику. Цель — не каркас, а небольшой клиент, который ведёт себя в точности как команда оболочки и легко расширяется.

Самый чистый подход — хранить тело запроса в одном общем месте, чтобы версии для curl и Python никогда не расходились. Определите его как словарь, сериализуйте, а лёгкая обёртка пусть занимается HTTP-деталями.

import json
import os
import requests

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


def build_payload(prompt: str, **overrides) -> dict:
    payload = {
        "model": "flux-3-image-klein",
        "prompt": prompt,
    }
    payload.update(overrides)
    return payload


def generate_image(prompt: str, timeout: float = 60.0, **overrides) -> dict:
    response = requests.post(
        f"{BASE_URL}/v1/images/generations",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        data=json.dumps(build_payload(prompt, **overrides)),
        timeout=timeout,
    )
    response.raise_for_status()
    return response.json()


if __name__ == "__main__":
    result = generate_image(
        "Старый обветренный маяк на скале в сумерках, длинная выдержка, мягкий туман"
    )
    print(json.dumps(result, indent=2))

Почему такая структура выгодна:

  • build_payload — единственное место, где собирается тело запроса. Добавьте там параметр, и он автоматически появится и в исследовательском скрипте, и в продакшен-коде.
  • raise_for_status() немедленно превращает HTTP-сбой в исключение, поэтому вы никогда случайно не примете тело ошибочного ответа за успешный результат.
  • Явный timeout предотвращает классическое зависание: застрявшее соединение бесконечно блокирует рабочий поток. Выберите значение, соответствующее собственному бюджету времени запроса сервиса.
  • Базовый URL и ключ из переменных окружения означают, что один и тот же код без изменений работает в предпродакшене и продакшене.

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

Работа с параметрами размера и стиля

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

Держите необязательные параметры в явном блоке

Никогда не разбрасывайте магические строки по коду. Расширьте сборщик тела запроса именованными параметрами и валидируйте на границе:

def build_payload(prompt: str, size: str | None = None, style: str | None = None) -> dict:
    payload = {"model": "flux-3-image-klein", "prompt": prompt}
    if size:
        payload["size"] = size
    if style:
        payload["style"] = style
    return payload

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

Сверяйтесь с документацией, а не с предположениями

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

  1. Прочитайте текущий справочник параметров flux-3-image-klein в документации HiAPI, запишите допустимые значения как константу в кодовой базе и добавьте комментарий со страницей документации и датой проверки.
  2. Перед сборкой запроса проверяйте ввод пользователя или вызывающего кода по этой константе. Быстро падайте с понятным локальным сообщением об ошибке, а не отправляйте заведомо неудачный запрос в сеть.
  3. Когда запрос возвращает ошибку валидации из-за неподдерживаемого значения, обновляйте константу по документации, а не угадывайте соседнее значение, которое «кажется правильным».

Небольшой кортеж ALLOWED_SIZES плюс одна проверка на вхождение стоит почти ничего, но устраняет целый класс обращений в поддержку. То же самое со стилевыми подсказками: относитесь к ним как к закрытому набору, который вы проверили, а не как к открытой строке, которую, как вы надеетесь, сервер стерпит.

Пакетные запросы и повтор при сбоях

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

Параллелизм с трассировкой

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

from concurrent.futures import ThreadPoolExecutor, as_completed

def run_batch(prompts: list[str], max_workers: int = 4) -> list[dict]:
    results = []
    with ThreadPoolExecutor(max_workers=max_workers) as pool:
        futures = {pool.submit(generate_image, p): p for p in prompts}
        for future in as_completed(futures):
            prompt = futures[future]
            try:
                results.append({"prompt": prompt, "ok": True, "data": future.result()})
            except Exception as exc:
                results.append({"prompt": prompt, "ok": False, "error": str(exc)})
    return results

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

Повторы с экспоненциальной задержкой

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

import time

def generate_with_retry(prompt: str, attempts: int = 3, **overrides) -> dict:
    delay = 1.0
    for attempt in range(1, attempts + 1):
        try:
            return generate_image(prompt, **overrides)
        except requests.HTTPError as exc:
            status = exc.response.status_code if exc.response is not None else None
            if status is not None and 400 <= status < 500 and status != 429:
                raise
            if attempt == attempts:
                raise
        except requests.Timeout:
            if attempt == attempts:
                raise
        time.sleep(delay)
        delay *= 2
    raise RuntimeError("unreachable")

Записывайте одну строку журнала на каждую попытку с идентификатором промпта, номером попытки и статусом. Когда пакетный прогон идёт не так, именно этот журнал показывает, столкнулись вы с временным сбоем или с системной проблемой тела запроса.

Устранение типичных ошибок запросов

Большинство сбоев в первую неделю — не проблема модели, а проблема конвейера. Ниже классы, которые вы встретите вероятнее всего, и конкретные исправления для каждого.

401 / 403 — аутентификация и авторизация

Симптом: отказ сразу, до какой-либо генерации. Причина: отсутствует заголовок Authorization, неверный формат bearer-токена, ключ истёк или отозван, либо в переменную окружения вклеились пробельные символы. Исправление: выведите первые и последние несколько символов фактически отправляемого ключа (никогда не печатайте ключ целиком), убедитесь, что заголовок имеет вид Bearer <key> ровно с одним пробелом, и проверьте, что ключ активен в вашей учётной записи HiAPI. Если ключ работает в curl, но не в Python, разница почти всегда в том, как собирается заголовок.

400 — валидация тела запроса

Симптом: запрос понят, но отклонён из-за какого-то поля. Причина: опечатка в model, отсутствует prompt, неподдерживаемый size или значение стиля, либо неверный тип (число там, где нужна строка). Исправление: сравните ваше сериализованное тело — json.dumps(build_payload(...)) — со схемой в документации символ за символом. Валидируйте необязательные параметры локально по константам, выведенным из документации, чтобы плохие значения никогда не покидали процесс.

404 — неверный маршрут

Симптом: сама конечная точка не найдена. Причина: опечатка в пути, устаревший базовый URL или несовпадение косой черты при склейке фрагментов URL. Исправление: собирайте URL из одной константы и сверяйте со справочником конечных точек в документации HiAPI, а не со скопированным фрагментом кода.

429 — ограничение скорости

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

Тайм-ауты и сбросы соединения

Симптом: вызовы долго висят или посреди пакета появляются исключения ReadTimeout. Причина: слишком агрессивный тайм-аут клиента, нестабильная сеть или исчерпание пула соединений большим пакетом. Исправление: задайте явный, но реалистичный тайм-аут на каждый запрос, повторяйте тайм-ауты с задержкой и держите параллелизм умеренным. Никогда не убирайте тайм-аут, чтобы «заставить это работать» — так видимый сбой превращается в невидимое зависание.

Успех, но изображение не то

Это проблема промпта, а не API. Расплывчатые промпты, конфликтующие подсказки стиля и промпты, противоречащие явному size, дают неожиданный вывод. Сначала уточните описание в промпте; только потом пересматривайте параметры.

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

Прежде чем направлять продакшен-трафик на flux-3-image-klein, пройдите этот чек-лист. Это займёт несколько минут, но отловит сбои, которые дорого обходятся в продакшене.

  • Учётные данные — ключ загружается из переменной окружения или менеджера секретов и никогда не коммитится; подтверждено, что он работает для генерации изображений в учётной записи, с которой вы планируете списывать средства.
  • Конечная точка — базовый URL и маршрут дословно взяты из текущей документации HiAPI и хранятся как одна константа.
  • Структура тела запроса — имя модели написано в точности как в документации, prompt всегда присутствует и не пуст, необязательные параметры опускаются, когда не нужны, и валидируются локально, когда заданы.
  • Значения параметров — константы size и стиля сверены с документацией на дату в комментарии, и есть план перепроверки после обновлений API.
  • Стратегия повторов — временные ошибки и тайм-ауты повторяются с задержкой, клиентские ошибки падают быстро, число попыток ограничено.
  • Параллелизм — max_workers установлен консервативно и повышается только после чистых пакетных прогонов.
  • Тайм-ауты — заданы явно для каждого запроса; нет пути, где зависший вызов навсегда блокирует рабочий поток.
  • Наблюдаемость — одна строка журнала на попытку с идентификатором промпта, номером попытки, статусом и задержкой; каждый результат в пакетном выводе можно отнести к конкретному запросу.
  • Артефакты сбоев — сохранены как минимум один реальный успешный и один реальный ошибочный ответ в качестве тестовых фикстур.

Если хоть один пункт не отмечен, исправить это сейчас дешевле, чем отлаживать в два часа ночи. Когда чек-лист полностью зелёный, у вас есть небольшой, наблюдаемый и расширяемый клиент, а не скрипт, к которому страшно прикасаться. За authoritative-справочником параметров и любыми обновлениями конечных точек добавьте документацию HiAPI в закладки и опирайтесь на неё как на окончательный источник.

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

Все статьи →

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

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

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