Как использовать flux-2/image-to-image через hiapi API: curl, Python и рабочие примеры запросов

Кратко

• Что это: рабочий способ вызова flux-2/image-to-image API на hiapi — создать задачу, опрашивать статус, скачать результат.
• Эндпоинт: используйте POST https://api.hiapi.ai/v1/tasks с "model": "flux-2/image-to-image", затем GET /v1/tasks/<taskId>, пока задача не достигнет терминального состояния.
• Обязательные поля ввода (все четыре): prompt, image_urls (1–8 публичных URL — это и есть функция нескольких референсов), aspect_ratio и resolution (1K или 2K).
• Схема строгая. Таких полей, как strength или fidelity, не существует — они будут отклонены с кодом 400. Точность контролируется вашими референсными изображениями, промптом и resolution — а не отдельной ручкой.

Что вы создаёте и что нужно подготовить

Цель: отправить в flux-2 одно или несколько референсных изображений плюс текстовый промпт и получить обратно скачиваемое отредактированное/перерисованное изображение — через curl или Python, без SDK.

Предварительные требования:

1. Ключ hiapi API — создайте в консоли hiapi. Ключ имеет вид sk-... и передаётся в заголовке Authorization: Bearer.
2. Как минимум один публично доступный URL изображения в качестве референса. API загружает image_urls на стороне сервера, поэтому ссылки на localhost или URL приватных бакетов не подойдут — используйте публичный бакет, CDN или предподписанный URL.
3. curl или Python 3.8+ с requests (pip install requests).

Схема запроса

flux-2/image-to-image работает через единый интерфейс задач hiapi. Объект input принимает ровно следующие поля:

Поле	Тип	Обязательно	Описание
prompt	string	Да	Что нужно изменить или сгенерировать. Минимум 3 символа.
image_urls	string[]	Да	1–8 публичных URL изображений. Больше одного = несколько референсов: flux-2 объединяет идентичность, продукт или стилистические признаки со всех референсов.
aspect_ratio	string	Да	Одно из: 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3 или auto (следует за референсом).
resolution	string	Да	1K или 2K.

Любые другие поля будут отклонены. Например, отправка поля strength или fidelity вернёт:

{
  "code": 400,
  "error_code": "INVALID_REQUEST",
  "message": "invalid input: <root>: additional properties 'fidelity', 'strength' not allowed"
}

Это стоит запомнить: в режиме image-to-image у flux-2 нет ручки силы шума. То, насколько точно вывод соответствует референсу (редактирование с «высокой точностью» против свободной перерисовки), зависит от того, как вы пишете промпт — например, «Сохрани продукт, его этикетку и пропорции точно как на референсе; замени только фон» — плюс использование resolution: "2K" для работ, требующих детализации.

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

Шаг 1 — создать задачу:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2/image-to-image",
    "input": {
      "prompt": "Place this product on a white marble countertop with soft morning light, keep the product itself unchanged",
      "image_urls": ["https://your-cdn.example.com/product.jpg"],
      "aspect_ratio": "1:1",
      "resolution": "2K"
    }
  }'

При успешном создании ID задачи возвращается в data.taskId.

Шаг 2 — опрашивать до завершения:

curl -s https://api.hiapi.ai/v1/tasks/TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

Продолжайте опрашивать каждые несколько секунд, пока data.status не станет терминальным. При "status": "success" URL изображения находится в data.output[0].url.

Шаг 3 — сразу скачать результат:

curl -s -o result.jpg "OUTPUT_URL"

URL вывода содержит метку времени expireAt — они временные. Сразу после успеха задачи скачивайте байты (или копируйте в своё хранилище); не используйте вывод задачи напрямую через горячие ссылки в продакшене.

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

Полный скрипт — создание, опрос, скачивание — только с requests:

import time
import requests

API_KEY = "sk-YOUR_KEY"
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def create_task() -> str:
    resp = requests.post(BASE, headers=HEADERS, json={
        "model": "flux-2/image-to-image",
        "input": {
            "prompt": ("Combine the person from the first image with the jacket "
                       "from the second image, studio lighting, neutral backdrop"),
            "image_urls": [
                "https://your-cdn.example.com/person.jpg",
                "https://your-cdn.example.com/jacket.jpg",
            ],
            "aspect_ratio": "3:4",
            "resolution": "2K",
        },
    }, timeout=30)
    body = resp.json()
    task_id = (body.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"create failed: {body}")
    return task_id

def wait_task(task_id: str, timeout_s: int = 600, poll_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        task = requests.get(f"{BASE}/{task_id}", headers=HEADERS,
                            timeout=30).json().get("data") or {}
        status = task.get("status")
        if status == "success":
            return task
        if status == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(poll_s)
    raise TimeoutError(f"task {task_id} still running after {timeout_s}s")

task_id = create_task()
print("task:", task_id)
task = wait_task(task_id)
url = task["output"][0]["url"]          # 临时 URL——请立即保存
img = requests.get(url, timeout=120).content
with open("result.jpg", "wb") as f:
    f.write(img)
print("saved result.jpg,", len(img), "bytes")

Обратите внимание, что здесь в image_urls используется два изображения — это и есть практическое применение нескольких референсов. Принимается до 8 референсных изображений; модель комбинирует их между собой (человек + одежда, продукт + стиль фона, персонаж + референс позы и т. д.).

Рекомендации для продакшена

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

{
  "model": "flux-2/image-to-image",
  "input": { "...": "..." },
  "callback": { "url": "https://your-app.example.com/hooks/hiapi", "when": "final" }
}

С "when": "final" вы получите ровно один POST, когда задача достигнет терминального состояния. Эмпирическое правило: опрос подходит для CLI, пакетной обработки и любых короткоживущих сценариев; callback лучше для пользовательских приложений, поскольку удержание цикла опроса в воркере на каждое изображение не масштабируется. Если вы не можете открыть публичный эндпоинт callback, тогда опрашивайте — но увеличивайте интервал с экспоненциальной задержкой до 5 секунд и более.

Сделайте повторные попытки безопасными. Относитесь к созданию задачи как к побочному эффекту, которым оно и является: сохраняйте возвращённый taskId в своей записи о задании до того, как действовать по результату; при повторной попытке проверяйте статус уже сохранённой задачи, а не создавайте новую вслепую (каждое успешное создание тарифицируется отдельно). Если ваш раннер заданий может сработать дважды, сначала выполните дедупликацию по вашему собственному ID задания.

Обрабатывайте ошибки, которые реально встретите:

• 401 permission_denied — неверный ключ или у ключа нет прав на эту модель. Тело ответа:

  {"error": {"code": "permission_denied",
             "message": "This API key cannot use the selected model. ...",
             "type": "hiapi_error"}}
  

  Проверьте ключ в консоли; наш чек-лист по недействительным API-ключам охватывает частые причины.

• 400 INVALID_REQUEST — нарушение схемы. message перечислит все нарушающие поля сразу (отсутствующие обязательные поля, неверные значения перечисления, неизвестные дополнительные поля), поэтому читайте его целиком, а не исправляйте по одному полю за попытку.

• Задача status: "fail" — задача принята, но генерация не удалась; ошибка находится в data.error. Обрабатывайте её в цикле опроса/callback, а не при создании.

• Истёк URL вывода — если скачивание возвращает 4xx через несколько минут после успеха, вы слишком долго ждали. Перепроверьте expireAt и всегда скачивайте сразу.

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

• Страница модели flux-2/image-to-image — параметры и текущие цены
• Страница модели flux-2/text-to-image — та же серия, без референсов
• flux-2 для изображений товаров в e-commerce — сквозное решение на основе text-to-image
• FLUX 1.1 Pro на hiapi — сравнение с предыдущим поколением
• Цены hiapi — стоимость за изображение по разрешениям

Частые вопросы

Сколько референсных изображений можно передать в flux-2 image-to-image? От 1 до 8, в виде публичных URL в image_urls. Больше 8 приводит к ошибке валидации (maxItems: got N, want 8).

Есть ли параметр strength или fidelity? Нет. Схема ввода принимает только prompt, image_urls, aspect_ratio и resolution; неизвестные поля отклоняются с кодом 400. Точность контролируйте формулировкой промпта (явно указывайте, что должно остаться неизменным), а при важности деталей используйте 2K.

Какие разрешения и соотношения сторон поддерживаются? resolution — 1K или 2K. aspect_ratio — одно из: 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3 или auto — auto следует за вашим референсом, что обычно и нужно при редактировании.

Можно ли отправить base64-изображение вместо URL? Нет — image_urls принимает URL, и они должны быть публично доступны, чтобы API мог их загрузить. Загрузите в бакет или CDN, затем передайте полученный URL (предподписанные URL работают).

Сколько стоит каждое изображение в flux-2 image-to-image? Цена зависит от разрешения — смотрите текущий тариф за изображение на странице модели flux-2/image-to-image и на странице цен.

Как долго действуют URL сгенерированных изображений? URL вывода временные и содержат поле expireAt. Сразу после успеха задачи скачивайте байты изображения и храните их самостоятельно.

В чём разница между flux-2/image-to-image и flux-2/text-to-image? Одна серия моделей, разные режимы: text-to-image генерирует только по промпту, тогда как image-to-image требует 1–8 референсных изображений и редактирует или комбинирует на их основе. Схемы ввода различаются, поэтому тела запросов не взаимозаменяемы.