Как использовать flux-2-klein-4b/image-to-image через hiapi API

FLUX.2 [klein] 4B — это компактная и быстрая модель редактирования изображений от Black Forest Labs: передайте ей опорное изображение и инструкцию на естественном языке, и она вернёт отредактированное изображение размером до 4 МП. В hiapi она, как и все остальные модели, работает через один и тот же Unified Async API — создайте задачу с помощью POST /v1/tasks, затем опрашивайте статус или получайте результат через callback. Это руководство охватывает точную структуру запроса, рабочие примеры на curl/Python и то, как подключить модель к производственной среде.

Что вам понадобится

• API-ключ hiapi. Его можно получить в dashboard — ключ имеет вид sk-... и передаётся в заголовке Authorization: Bearer.
• Публично доступный URL опорного изображения (jpeg, png или webp — svg не поддерживается). Изображения размером более 4 МП автоматически уменьшаются до 4 МП.
• Актуальная цена flux-2-klein-4b/image-to-image зависит от разрешения (от 0.25 МП до 4 МП) — смотрите hiapi pricing для актуальных цен, не задавайте их жёстко здесь.

Минимальный рабочий пример

Идентификатор модели — flux-2-klein-4b/image-to-image — используйте его строго в таком виде (со слэшем) как значение model (не в пути URL). Все модели hiapi используют один и тот же эндпоинт; различаются только поля объекта input.

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-klein-4b/image-to-image",
    "input": {
      "prompt": "Keep the subject and camera angle. Replace the background with a deep-blue studio gradient and add soft rim lighting.",
      "image_urls": ["https://your-cdn.example.com/product-shot.jpg"],
      "resolution": "2 MP",
      "aspect_ratio": "16:9"
    }
  }'

Этот запрос сразу возвращает taskId — генерация выполняется асинхронно:

{"code": 0, "message": "success", "data": {"taskId": "task_..."}}

Опрос для получения результата:

curl "https://api.hiapi.ai/v1/tasks/task_..." \
  -H "Authorization: Bearer sk-YOUR_API_KEY"

Когда status становится "success", отредактированное изображение находится в data.output[0].url. Этот URL временный (содержит expireAt), поэтому сразу скачайте или перезагрузите файл — не храните эту горячую ссылку напрямую.

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

import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer sk-YOUR_API_KEY",
    "Content-Type": "application/json",
}

def create_task(prompt: str, image_url: str) -> str:
    payload = {
        "model": "flux-2-klein-4b/image-to-image",
        "input": {
            "prompt": prompt,
            "image_urls": [image_url],
            "resolution": "2 MP",
            "aspect_ratio": "16:9",
        },
    }
    resp = requests.post(API, headers=HEADERS, json=payload, timeout=30)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]

def wait_task(task_id: str, timeout_s: int = 300, poll_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30)
        task = r.json()["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {task.get('error')}")
        time.sleep(poll_s)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

task_id = create_task(
    "Keep the subject and camera angle. Replace the background with a deep-blue "
    "studio gradient and add soft rim lighting.",
    "https://your-cdn.example.com/product-shot.jpg",
)
result = wait_task(task_id)
print(result["output"][0]["url"])

Параметры запроса

flux-2-klein-4b/image-to-image принимает строгую схему входных данных — дополнительные поля, не перечисленные здесь, отклоняются с ответом 400:

Поле	Обязательно	Описание
prompt	Да	Описание редактирования на естественном языке.
image_urls	Да	Массив, содержащий ровно один URL опорного изображения. Передача нескольких вернёт maxItems: got N, want 1.
resolution	Нет	Одно из значений: 0.25 MP, 0.5 MP, 1 MP (по умолчанию), 2 MP, 4 MP. Используйте 0.25/0.5 MP для дешёвых черновиков и 2/4 MP для финального результата.
aspect_ratio	Нет	Одно из значений: match_input_image (по умолчанию), 1:1, 16:9, 9:16, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 21:9, 9:21.
seed	Нет	Целое число для воспроизводимости результатов между в остальном идентичными запросами.
output_format	Нет	jpg (по умолчанию), png или webp.
output_quality	Нет	Целое число, качество сжатия для jpg/webp (по умолчанию 95).

У этой модели нет полей size или n — это соглашения других провайдеров, и данная схема их не распознаёт. У каждой модели hiapi свой набор полей, поэтому прежде чем переносить запросы, созданные для других моделей, ознакомьтесь со справочной страницей модели.

Рекомендации для производственной среды

Отдавайте предпочтение callback, а не опросу. Добавьте объект callback верхнего уровня, и hiapi уведомит ваш сервис, вместо того чтобы вы опрашивали в цикле:

{
  "model": "flux-2-klein-4b/image-to-image",
  "input": { "prompt": "...", "image_urls": ["..."] },
  "callback": { "url": "https://your-domain.com/hiapi/callback", "when": "final" }
}

when принимает только "final" — уведомление отправляется один раз, когда задача достигает конечного состояния (success или fail), а не поток прогресса. Рассматривайте callback как сигнал пробуждения: получив его, всё равно выполните GET /v1/tasks/<taskId>, чтобы прочитать авторитетный статус, и сделайте обработчик идемпотентным по taskId на случай повторной доставки.

Идемпотентность. Сразу после возврата из create_task сохраните taskId, прежде чем начинать опрос или ждать callback. Если процесс упадёт во время ожидания, после перезапуска восстановите состояние с помощью GET /v1/tasks/<taskId>, а не создавайте задачу заново — создание задачи является платным событием, а GET можно повторять бесплатно.

Обработка ошибок. Недействительный или неавторизованный ключ возвращает HTTP 401 и структурированное тело ответа:

{
  "error": {
    "code": "permission_denied",
    "message": "This API key cannot use the selected model. Please check permissions or use another key. If the issue persists, contact support with request ID: ...",
    "request_id": "...",
    "type": "hiapi_error"
  }
}

Запишите request_id — служба поддержки сможет по нему найти точный вызов. Некорректный input (отсутствует prompt/image_urls, неподдерживаемое значение aspect_ratio или нераспознанные дополнительные поля) возвращает 400 с error_code: "INVALID_REQUEST" и указанием проблемного поля в сообщении; исправьте тело запроса, а не повторяйте его как есть.

Связанные материалы

• Справочник модели FLUX.2 [klein] 4B для преобразования изображения в изображение — полная документация параметров и примеры тел запросов.
• Справочник модели FLUX.2 [klein] 4B для генерации изображений по тексту — соответствующий вариант текст-в-изображение, не требующий опорного изображения.
• hiapi pricing — текущая стоимость одной генерации с разбивкой по разрешению.
• Обзор Unified Async API — общий для всех моделей платформы контракт POST /v1/tasks / GET /v1/tasks/:id.

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

Какие форматы изображений принимает image_urls? jpeg, png или webp. svg не поддерживается. Изображения размером более 4 МП автоматически уменьшаются до 4 МП перед редактированием.

Можно ли передать несколько опорных изображений? Нет — image_urls в этой модели ограничен ровно одним элементом. Передача большего числа возвращает 400 (maxItems: got N, want 1).

Почему мой запрос отклоняется с сообщением "additional properties ... not allowed"? Схема строгая: любое поле, отсутствующее в таблице параметров выше (например, соглашения других провайдеров вроде size, n или strength), вызывает 400. Смотрите справочник модели, чтобы узнать точный набор допустимых полей.

Как сохранить исходное соотношение сторон изображения? Установите aspect_ratio в match_input_image — это также значение по умолчанию, если полностью опустить это поле.

В чём разница между flux-2-klein-4b/image-to-image и вариантом 9B? Оба используют одну и ту же схему запроса (prompt, image_urls, resolution, aspect_ratio, seed, output_format, output_quality). Вариант 9B жертвует частью скорости и стоимости ради более сильного реализма, рендеринга текста и детализации — используйте 4B, когда быстро и недорого итерируете, и 9B, когда редактирование должно выдерживать проверку на мелких деталях.

Нужен ли мне callback URL, или достаточно опроса? Опрос через GET /v1/tasks/:id подходит для локальной разработки, небольших объёмов или как запасной вариант, если доставка callback пропущена. Для производственного трафика callback избавляет от накладных расходов на цикл опроса при каждом запросе.