Руководство
Использование flux-2/image-to-image через HiAPI API: учебник по curl и Python
На этой странице
Назначение и сценарии применения flux-2/image-to-image
flux-2/image-to-image — это эндпоинт для редактирования, а не чистый генератор текста в изображение. Ему нужно передать две вещи: референсное изображение и инструкцию по редактированию на естественном языке. Модель читает референсное изображение как визуальный контекст — субъект, композицию, стиль, освещение — и генерирует новое изображение, которое следует вашей инструкции и при этом привязано к этому референсу.
При проектировании конвейера это различие важно. При генерации из текста вы описываете всё с нуля и надеетесь, что модель окажется близко к вашему замыслу. При работе с изображением в изображение у вас уже есть визуальный материал, и вам нужна контролируемая трансформация: перестилизация изображения продукта, замена фона, настройка атмосферы сцены или итерация дизайна при сохранении стабильной базовой композиции.
Подходящие сценарии
- Вариации материала. Генерация нескольких стилизованных обработок на основе одного одобренного референса.
- Направленное редактирование. Применение точечных изменений («сделать освещение теплее», «заменить фон на однотонную студийную стену») без необходимости перегенерировать всю сцену.
- Согласованность серии результатов. Повторное использование одного и того же референса, чтобы пакет выходных данных имел общий визуальный якорь.
- Инструменты совместной работы. Позволить пользователям загружать изображения, описывать изменения и получать результат в вашем интерфейсе.
Неподходящие сценарии
- Попиксельно точная ретушь или композитинг. Это генеративная модель, а не растровый редактор.
- Ситуации без референсного изображения вообще — в этом случае генерация из текста будет лучшей отправной точкой.
- Любые рабочие процессы, где предполагается, что инструкция должна нести все детали; референс реально влияет на результат, и плохой референс даст плохой результат.
Понимайте этот эндпоинт как референсное изображение + инструкция -> отредактированное изображение. Всё в этом учебнике строится вокруг этой формы: как отправлять, как читать возвращённый результат и как поддерживать работу при проблемах с сетью.
Предварительные требования и настройка аутентификации
Перед первым вызовом подготовьте три вещи.
1. Аккаунт HiAPI
Зарегистрируйтесь и откройте консоль. Все запросы в этом учебнике отправляются через единый API HiAPI, поэтому не нужно отдельно регистрироваться у провайдеров и устанавливать SDK для каждого из них.
2. API-ключ
Создайте API-ключ в консоли. Обращайтесь с ним как с паролем: не коммитьте в репозиторий, не вставляйте в клиентский код и не записывайте в логи. Стандартная практика — загружать его из переменной окружения во время выполнения:
export HIAPI_API_KEY="your-api-key-here"
Затем ссылайтесь на HIAPI_API_KEY там, где нужен ключ. Если вы развёртываете в контейнере или на бессерверной платформе, установите его как секрет в этом окружении, а не вшивайте в образ.
3. Доступное референсное изображение
Эндпоинту требуется референсное изображение, поэтому заранее решите, как его предоставить. Два распространённых способа:
- URL, который API может загрузить, например подписанная ссылка на ваше объектное хранилище.
- Байты в кодировке Base64, отправляемые встроенно в теле запроса, что позволяет не раскрывать внутренние URL, но увеличивает размер полезной нагрузки.
Начните с небольшого тестового изображения — нескольких сотен КБ достаточно для проверки интеграции. Загрузка больших файлов замедляет каждую повторную попытку и усложняет отладку.
Контрольная точка
К этому моменту у вас должен быть ключ, хранящийся в переменной окружения, и тестовое изображение, доступное с вашей машины. Постарайтесь, чтобы ключ не попадал в историю shell (файл .env, загружаемый инструментом, обычно чище, чем встроенный экспорт в командной строке).
Ещё одна привычка, которую стоит завести с самого начала: с первого дня записывайте ID запросов и время выполнения. Когда в продакшене что-то идёт не так, разница между отслеживаемым и неотслеживаемым запросом огромна.
Построение запроса: референсное изображение и инструкция по редактированию
Каждый вызов изображение-в-изображение строится вокруг двух входных данных. Сделайте их правильно, и остальное — это работа с инфраструктурой.
Вход первый: референсное изображение
Референсное изображение — это якорь. Оно сообщает модели, что содержит сцена и как она выглядит до любых правок. Практические советы:
- Соответствуйте желаемому соотношению сторон вывода. Если референс — широкоформатное горизонтальное изображение, а вам нужен квадратный вывод, в зависимости от конфигурации вызова ожидайте обрезки или искажения.
- Начинайте с чистого, хорошо освещённого изображения. Мутный референс даст мутный результат редактирования.
- Лучше один чёткий субъект. Захламлённый коллаж даёт модели слишком много конкурирующих якорей.
Вход второй: инструкция по редактированию
Инструкция — это описание желаемых изменений на естественном языке. Здесь возникает большинство различий в качестве. Относитесь к ней как к промпту, приложенному к референсному изображению.
- Описывайте изменение, а не всю сцену. «Заменить фон на чисто белую студийную стену» лучше, чем «продукт на белом фоне» — последнее подталкивает модель перерисовать всё.
- Указывайте, что должно остаться. Формулировки вроде «сохранить позу и композицию субъекта без изменений» заметно снижают отклонение.
- Конкретизируйте стиль и освещение. «Мягкий пасмурный свет, приглушённые цвета» даёт модели больше полезной информации, чем «сделать красивее».
- Избегайте противоречий. Если референс — дневная уличная сцена, а вы просите ночное помещение, ожидайте, что модель примет решение, которое вам может не понравиться.
Тело запроса
Запрос, который вы отправляете в flux-2/image-to-image, содержит идентификатор модели, референсное изображение и инструкцию. Полезная мысленная модель:
{
"model": "flux-2/image-to-image",
"input": {
"image": "<URL или base64 референсное изображение>",
"prompt": "<инструкция по редактированию>"
}
}
Если ваш референс в base64, сформируйте data URI согласно схеме запроса или передайте исходную кодировку вместе с MIME-типом. Если это URL, убедитесь, что ссылка общедоступна во время вызова — подписанная ссылка, истекающая в середине запроса, приводит к непонятным сбоям.
Сначала итерации, потом интеграция
Прежде чем подключать что-либо к коду, напишите две-три инструкции для одного и того же референса и сравните выводы. При конкретных инструкциях модель ведёт себя предсказуемо; при расплывчатых — нестабильно. Узнать это сейчас гораздо дешевле, чем в продакшене.
Рабочий запрос curl
Самый быстрый способ проверить ключ, референсное изображение и инструкцию — один вызов curl. Пример ниже предполагает, что ваш ключ находится в HIAPI_API_KEY, а референс доступен по URL.
curl -sS -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "flux-2/image-to-image",
"input": {
"image": "https://your-bucket.example.com/reference.jpg",
"prompt": "Заменить фон на чисто белую студийную стену. Сохранить позу, композицию и освещение на субъекте без изменений."
}
}'
На что обратить внимание:
- Ключ передаётся через заголовок
Authorizationкак bearer-токен. Никогда не помещайте его в URL. Content-Type— JSON. Забыть указать его — частая причина непонятных 4xx.- ID модели находится в теле запроса, поэтому тот же эндпоинт можно перенаправить к другим моделям, изменив одно поле.
- Инструкция — это полное предложение, а не список ключевых слов. Это сделано намеренно — см. предыдущий раздел.
Чтение необработанного вывода
Сначала запустите один раз и посмотрите на весь ответ до написания какого-либо кода разбора. При необходимости обработайте его инструментом форматирования:
curl -sS -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @request.json | python -m json.tool
Хранить тело запроса в файле (request.json) проще для итераций, чем редактировать экранированные строки shell, и это даёт вам постоянный артефакт для воспроизведения ошибок в будущем.
Если нужен base64 вместо URL
Замените значение image на data URI, сформированный из вашего файла:
python - <<'PY'
import base64, json, pathlib
data = base64.b64encode(pathlib.Path("reference.jpg").read_bytes()).decode()
body = {
"model": "flux-2/image-to-image",
"input": {
"image": f"data:image/jpeg;base64,{data}",
"prompt": "Сделать освещение теплее и немного снизить контраст.",
},
}
pathlib.Path("request.json").write_text(json.dumps(body))
PY
Теперь тот же вызов curl будет работать, поскольку полезная нагрузка сохранена в request.json. Если вызов успешен, у вас есть всё необходимое для перехода к Python.
Тот же вызов на Python
Версия на Python намеренно проста: тот же словарь, та же отправка, а эндпоинт и модель вынесены в константы, чтобы не было расхождений с версией curl.
import os
import requests
API_URL = "https://api.hiapi.ai/v1/images/generations"
MODEL = "flux-2/image-to-image"
def edit_image(reference_url: str, instruction: str, timeout: float = 60.0) -> dict:
api_key = os.environ["HIAPI_API_KEY"] # немедленный сбой, если не задан
payload = {
"model": MODEL,
"input": {
"image": reference_url,
"prompt": instruction,
},
}
response = requests.post(
API_URL,
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json=payload,
timeout=timeout,
)
response.raise_for_status()
return response.json()
if __name__ == "__main__":
result = edit_image(
"https://your-bucket.example.com/reference.jpg",
"Заменить фон на чисто белую студийную стену. "
"Сохранить позу, композицию и освещение на субъекте без изменений.",
)
print(result)
Почему так организовано
- Используется
os.environ["HIAPI_API_KEY"], а не.get(), чтобы отсутствие ключа немедленно вызывало ошибку, а не отправляло неаутентифицированный запрос. timeoutзадан явно. Генерация изображений не мгновенна; запрос без тайм-аута в итоге заблокирует рабочий процесс.raise_for_status()вызывается до разбора. Вы хотите получить исключение при 4xx или 5xx, а не непонятныйKeyErrorгде-то позже.- Эндпоинт и модель — константы уровня модуля, что позволяет легко направить тестовый набор на заглушку сервера.
Использование base64-входа
Если вы передаёте байты вместо URL, закодируйте файл и сформируйте data URI в том же месте, где строится полезная нагрузка:
import base64, pathlib
def as_data_uri(path: str, mime: str = "image/jpeg") -> str:
raw = pathlib.Path(path).read_bytes()
return f"data:{mime};base64," + base64.b64encode(raw).decode()
Затем вызовите edit_image(as_data_uri("reference.jpg"), instruction). Отделите шаг кодирования от функции запроса, чтобы можно было модульно тестировать проверку и сборку промпта без обращения к сети.
Разбор ответа
Вызов возвращает JSON-объект. Теперь извлеките отредактированное изображение так, чтобы даже добавление полей в ответ в будущем не вызывало ошибок.
Сначала проверяйте, а не предполагайте
Во время разработки выведите необработанный ответ и обратите внимание, где находится ссылка на изображение — обычно URL или base64-полезная нагрузка, вложенная в структуру результата. Затем напишите аксессор, который проверяет её наличие, а не обращается напрямую к вложенным ключам.
def extract_image_url(response: dict) -> str:
data = response.get("data") or []
if not data:
raise ValueError(f"В ответе нет данных изображения: {response}")
first = data[0]
url = first.get("url") or first.get("b64_json")
if not url:
raise ValueError(f"Нераспознанная полезная нагрузка изображения: {first}")
return url
Две привычки, которые стоит сохранить в этом коде: громко падать, включая фактическую полезную нагрузку в сообщение об ошибке, и принимать любую форму (URL или base64), а не жёстко кодировать одну из них. Форматы ответов развиваются; выживают терпимые читатели.
Немедленно сохраняйте
Возвращённый URL может быть временным. Если изображение важно, загрузите его в той же задаче и сохраните в своё хранилище:
def persist(url: str, dest: str) -> None:
if url.startswith("data:"):
header, b64 = url.split(",", 1)
import base64, pathlib
pathlib.Path(dest).write_bytes(base64.b64decode(b64))
return
with requests.get(url, stream=True, timeout=60) as r:
r.raise_for_status()
with open(dest, "wb") as f:
for chunk in r.iter_content(1 << 16):
f.write(chunk)
Сохранение также даёт вам стабильный ключ для записи в базу данных, что гораздо полезнее, чем хранение ссылки, которая может устареть.
Проверяйте то, что получили
Дешёвые проверки выявляют дорогие ошибки. Убедитесь, что файл не пуст, его магические числа соответствуют какому-либо формату изображения и, по желанию, что его размеры соответствуют ожидаемым. Гораздо лучше отклонить повреждённое или обрезанное изображение на границе, чем передать его пользователю.
Записывайте информацию о происхождении
Храните ID модели, текст инструкции, ключ референсного изображения и временную метку вместе с выводом. Когда через три недели кто-то спросит, почему изображение выглядит именно так, эта запись будет ответом — и она делает повторный запуск конкретного редактирования тривиальным.
Повторные попытки и обработка ошибок в продакшене
Вызовы генерации изображений терпят неудачу по совершенно разным причинам, и смешивать их — классическая ошибка в продакшене.
Различайте временные и окончательные ошибки
- Временные — тайм-ауты, сброс соединения, ограничение скорости 429, ответы 5xx. Тот же запрос после паузы, скорее всего, будет успешным.
- Окончательные — 400 неверный запрос, 401 неверный или отсутствующий ключ, 404 неизвестная модель, ошибка валидации полезной нагрузки. Повторять их — пустая трата времени и денег, а также задержка реального исправления.
Повторяйте только первый тип. Для второго немедленно завершайте задачу с ошибкой и показывайте сообщение — оно почти всегда точно указывает, какое поле проблемное.
Повторные попытки с экспоненциальной задержкой и джиттером
import random, time, requests
RETRYABLE = {429, 500, 502, 503, 504}
def call_with_retries(fn, attempts: int = 5, base: float = 1.0):
last = None
for i in range(attempts):
try:
return fn()
except requests.HTTPError as e:
status = e.response.status_code if e.response is not None else None
if status not in RETRYABLE:
raise
last = e
except (requests.Timeout, requests.ConnectionError) as e:
last = e
delay = base * (2 ** i) + random.uniform(0, 0.5)
time.sleep(delay)
raise RuntimeError("Попытки исчерпаны") from last
Экспоненциальная задержка не даёт вам обрушиться на уже перегруженный сервис; джиттер предотвращает синхронные повторные попытки группы рабочих процессов. Всегда ограничивайте количество попыток и общее время — бесконечный цикл хуже чистого сбоя.
Соблюдайте ограничения скорости
При получении 429 перед задержкой следуйте любым подсказкам о повторной попытке в заголовках ответа. Если вы запускаете большие пакетные задачи, добавьте ограничение параллелизма на своей стороне, а не полагайтесь на сервер для регулирования.
Делайте ошибки видимыми
- Помечайте повторные попытки уникальным ID задачи и записывайте каждую попытку с её результатом и временем выполнения.
- Отправляйте метрики по частоте повторных попыток; медленный рост — раннее предупреждение о деградации где-то выше по потоку.
- После неудачи последней попытки перемещайте задачу в очередь недоставленных сообщений с полным телом ответа, а не просто сообщением «failed».
Идемпотентность и обоснованность затрат
Повторный запрос может быть успешно выполнен на сервере, даже если ваш клиент так и не увидел ответ. Если ваш продукт не терпит дублирующихся выходных данных, используйте свой ID для ключа задачи и выполняйте сверку перед повторной попыткой. И поскольку вызовы оплачиваются по факту использования, остерегайтесь циклов повторных попыток, незаметно раздувающих расходы — застрявший и бесконечно повторяющий потребитель — самый дорогой баг в этом отношении.
Распространённые ловушки и следующие шаги
Большинство проблем интеграции с flux-2/image-to-image возникает из-за небольшого набора ошибок. Перед выпуском проверьте свой код по этим пунктам.
- Расплывчатые инструкции. «Улучшить» даёт случайные результаты; «убрать текст с вывески и сохранить форму вывески» даёт пригодный результат. Конкретика — самый мощный рычаг качества.
- Несоответствующее референсное изображение. Неправильное соотношение сторон, размытое исходное изображение или загромождённый коллаж не спасти лучшим промптом.
- Просроченные URL. Подписанная ссылка, обрывающаяся в середине запроса, вызывает сбой, выглядящий как ошибка сервера. Используйте достаточно длительный срок действия или переходите на base64.
- Жёстко закодированная структура ответа. Прямое обращение к вложенным ключам превращает небольшое изменение схемы в отказ. Используйте защитный экстрактор с понятными ошибками.
- Отсутствие тайм-аута. Отсутствующий тайм-аут бессрочно занимает рабочий процесс и маскирует реальную проблему.
- Повтор окончательных ошибок. 400 не исправится сам. Прочитайте сообщение.
- Потеря вывода. Если возвращённый URL временный, а вы не сохранили изображение, у вас ничего нет.
- Небрежное логирование секретов и промптов. Ключи никогда не должны появляться в логах; предоставленные пользователем инструкции могут требовать редактирования в зависимости от вашей области.
Следующие шаги
Когда поток одиночного вызова стабилен, естественные расширения таковы: обернуть вызов в фоновую задачу, чтобы ваш интерфейс оставался отзывчивым; хранить пары инструкция/ответ, чтобы проводить A/B-тестирование формулировок промптов; если пользователи предоставляют свои изображения, добавить слой модерации или валидации на входе. Просмотрите страницу модели flux-2/image-to-image и документацию HiAPI, чтобы узнать, какие параметры могут понадобиться вашему случаю дальше. Создайте минимально работающее решение, измерьте его и позвольте качеству инструкций делать основную работу.
Похожие статьи
Все статьи →-
Руководство
Практическое руководство по gpt-6.2-sol: 5 ценных способов применения текстовой модели в бизнесе
-
Руководство
Практическое руководство по gpt-6.2-astra: интеграция и ключевые моменты реализации для 5 ценных текстовых сценариев
Чек-лист для разработчиков: от выбора сценариев до внедрения в инженерию
-
Руководство
Практические сценарии Tripo H3.1: 5 высокоценных применений и ключевые моменты реализации
От text-to-3D до multiview-восстановления: выбирайте правильный режим и параметры под бизнес-сценарий