HiAPI
Блог

Руководство

Как вызывать fibo-2.0/image-to-image через HiAPI API: практика с curl и Python

Nov 13, 2026
Обложка: смещённые слои бумаги цвета слоновой кости с угольно-чёрными краевыми линиями и вложенным листом ржаво-красного цвета, плоская композиция.
На этой странице

Место fibo-2.0/image-to-image в конвейере

Модель текст-в-изображение начинается с подсказки, а модель изображение-в-изображение — с уже имеющегося у вас изображения. Это различие кажется небольшим, но именно оно определяет место модели в конвейере: fibo-2.0/image-to-image — это не первый шаг, порождающий материал с нуля, а шаг редактирования, преобразующий существующее изображение.

Типичный рабочий процесс выглядит так: вы получаете или генерируете базовое изображение, отправляете его в fibo-2.0/image-to-image с инструкцией, описывающей нужные изменения, а возвращённый результат передаёте дальше — на модерацию, компоновку, хранение или в следующий вызов модели. Поскольку модель принимает и входное изображение, и подсказку, она может перерисовывать стиль, корректировать или преобразовывать описанные вами части, сохраняя при этом композицию, положение субъекта и общую структуру.

Когда выбирать изображение-в-изображение, а не текст-в-изображение

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

Что этот интерфейс требует от вас

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

Поскольку запрос по своей сути асинхронен, архитектуру интеграции следует строить вокруг этого: отправить, сохранить идентификатор задания, опрашивать до завершения задания, затем получить ссылку на результат. Остальная часть этого руководства как раз и посвящена построению такого процесса.

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

Перед первым вызовом нужно подготовить три вещи: учётные данные, правильное понимание формы интерфейса и подготовленное входное изображение.

Учётные данные

Все запросы к HiAPI API аутентифицируются с помощью API-ключа. Ключ должен храниться на сервере — ни в коем случае не встраивайте его в код браузера и не коммитьте в репозиторий. Самый чистый подход — читать его из переменной окружения, чтобы один и тот же код работал локально и в развёрнутой среде:

export HIAPI_API_KEY="your-api-key"

Если у вас ещё нет ключа, создайте его в консоли аккаунта HiAPI, прежде чем продолжать.

Форма интерфейса

В HiAPI API эта модель обозначается как fibo-2.0/image-to-image. Все вызовы моделей используют один базовый URL и одни и те же соглашения о запросах, а значит, как только у вас есть рабочий вызов, переключение на другую модель сводится в основном к изменению идентификатора модели и полей полезной нагрузки.

Подготовка входного изображения

Запросу изображение-в-изображение нужно настоящее изображение, а не URL, который, как вы надеетесь, он сможет разобрать. Заранее решите, как его предоставить: как локальный файл, загружаемый вместе с запросом, или как ссылку, которую принимает API; и до написания кода приложения убедитесь, что формат подходит. Две самые частые категории провалов при первом запросе: отправка пути, который существует только на вашем ноутбуке, и отправка файла в формате, который интерфейс не принимает.

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

  • Изображение — реальный файл, который может прочитать ваш язык программирования.
  • Подсказка описывает нужное редактирование простым языком, а не просто набором ключевых слов.
  • Вы понимаете, какие параметры передавать, а какие оставить по умолчанию.
  • Ваш API-ключ доступен в той среде, откуда исходит запрос.

Когда всё это готово, можно переходить к самому запросу.

Разбор рабочего curl-запроса построчно

Начните с curl. Он устраняет всю абстракцию между вами и HTTP-запросом, и в случае ошибки вы точно знаете, что проблема в запросе, а не в клиентской библиотеке.

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fibo-2.0/image-to-image",
    "prompt": "turn the scene into a soft watercolor illustration, keep the subject and framing",
    "image": "BASE64_ENCODED_IMAGE_OR_ACCEPTED_REFERENCE",
    "n": 1
  }'

Ниже по очереди объясняется роль каждой части.

Строка запроса

-X POST задаёт метод. URL — это базовый адрес HiAPI API плюс путь генерации изображений. Базовый адрес следует хранить в переменной или в конфигурационном значении, а не жёстко прописывать в нескольких местах, чтобы будущие изменения требовали правки в одном месте.

Заголовки запроса

Authorization: Bearer $HIAPI_API_KEY передаёт ваши учётные данные; shell раскрывает переменную окружения, которую вы ранее экспортировали, поэтому ключ не появляется в истории команд в буквальном виде. Content-Type: application/json сообщает API, что тело запроса следует разбирать как JSON. Отправка JSON-тела с пропуском этого заголовка — частая причина труднообъяснимых ошибок.

Полезная нагрузка

model обозначает fibo-2.0/image-to-image. prompt — это ваша инструкция: описывайте редактирование, а не всё выходное изображение целиком, поскольку входное изображение уже несёт структуру. image — это форма входного изображения, принимаемая интерфейсом; при прямом встраивании содержимое файла кодируется в base64. n управляет количеством запрошенных выходных изображений; оставить значение по умолчанию — самый безопасный старт.

Если изображение большое, встраивать его прямо в shell-команду становится громоздко. Сначала закодируйте его в файл и ссылайтесь на него, либо сразу переходите к Python-подходу из следующего раздела — там чтение файла и кодирование занимают одну строку.

Чтение ответа

Не предполагайте, что ответ содержит готовые байты изображения. Запустите curl-вызов и изучите JSON: вы ищете идентификатор задания или поле статуса, чтобы понять, завершена ли задача или ещё выполняется. Зафиксируйте структуру до написания любого кода разбора, поскольку форма ответа определяет, как вы будете опрашивать.

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

Python делает запрос более удобным в сопровождении и позволяет инкапсулировать его в функцию, переиспользуемую во всей кодовой базе. Ниже — лёгкий клиент, реализующий тот же запрос:

import base64
import os
import time

import requests

BASE_URL = "https://api.hiapi.ai/v1"
API_KEY = os.environ["HIAPI_API_KEY"]


def encode_image(path: str) -> str:
    with open(path, "rb") as f:
        return base64.b64encode(f.read()).decode("utf-8")


def submit_image_edit(image_path: str, prompt: str) -> dict:
    payload = {
        "model": "fibo-2.0/image-to-image",
        "prompt": prompt,
        "image": encode_image(image_path),
        "n": 1,
    }
    response = requests.post(
        f"{BASE_URL}/images/generations",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json=payload,
        timeout=60,
    )
    response.raise_for_status()
    return response.json()

Почему выбрана такая структура

Разделение encode_image и submit_image_edit делает обработку файлов и обработку HTTP независимыми и более простыми для тестирования. Чтение ключа из окружения при импорте приводит к немедленному сбою при его отсутствии, а не к 401 после нескольких слоёв. Явная установка timeout предотвращает бесконечное зависание рабочих процессов из-за застрявших соединений.

Обработка тела ответа

raise_for_status() превращает сбой на уровне HTTP в исключение, которое можно перехватить и залогировать вместе с телом ответа — это гораздо полезнее, чем молча разбирать объект ошибки как успешный результат. Получив разобранный JSON, зафиксируйте содержащийся в нём идентификатор задания, а во время разработки логируйте полный ответ, чтобы видеть, какие поля там на самом деле есть. Не пишите парсер на основе предположений; пишите его на основе фактически наблюдаемого ответа.

Сохранение переиспользуемости

Два небольших улучшения быстро окупаются: вынесите базовый URL и имя модели в константы, чтобы другие вызовы моделей использовали тот же клиент; и пусть функция отправки возвращает типизированную структуру (небольшой dataclass или dict с известными ключами), чтобы код опроса опирался на стабильный контракт.

Обработка асинхронного жизненного цикла и опрос

Задания на изображения не выполняются мгновенно. Интеграция должна рассматривать отправку и завершение как два отдельных события.

Шаг 1: отправить и сохранить

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

Шаг 2: опрос с экспоненциальной задержкой

Опрашивайте интерфейс статуса задания с разумным интервалом. Плотный цикл, непрерывно бомбардирующий интерфейс статуса, — это и пустая трата ресурсов, и самая частая асинхронная ошибка:

def wait_for_job(job_id: str, interval: float = 2.0, max_wait: float = 180.0) -> dict:
    deadline = time.monotonic() + max_wait
    while time.monotonic() < deadline:
        response = requests.get(
            f"{BASE_URL}/jobs/{job_id}",
            headers={"Authorization": f"Bearer {API_KEY}"},
            timeout=30,
        )
        response.raise_for_status()
        job = response.json()
        if job.get("status") in {"succeeded", "failed"}:
            return job
        time.sleep(interval)
        interval = min(interval * 1.5, 10.0)
    raise TimeoutError(f"job {job_id} did not finish in {max_wait}s")

Начинайте с короткого интервала и постепенно его увеличивайте: это сохраняет отзывчивость ранних проверок и избегает долгосрочных частых запросов. Жёсткий предельный срок предотвращает бесконечное ожидание задания, которое никогда не завершится.

Шаг 3: считать неудачу нормальным результатом

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

Шаг 4: получить и сохранить результат

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

Частые ошибки и способы их исправления

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

Сбои аутентификации

401 или 403 почти всегда означают неверный заголовок или отсутствующий ключ. Убедитесь, что заголовок в точности Authorization: Bearer <key>, с одним пробелом после Bearer; и убедитесь, что переменная окружения действительно задана в процессе, откуда исходит запрос — а не только в вашей интерактивной оболочке. Ключ, вставленный с завершающим пробелом или лишними кавычками, составляет изрядную долю таких проблем.

Неверный формат полезной нагрузки

400 или 422 обычно означают, что API не может интерпретировать тело запроса. Проверьте три вещи по порядку: присутствует ли Content-Type: application/json, действительно ли JSON разбирается (завершающая запятая ломает его), присутствуют ли обязательные поля под правильными именами. Если вы отправляете данные изображения в base64, убедитесь, что это корректный base64, а базовый формат файла поддерживается — усечённая или дважды закодированная строка даёт запутанные ошибки валидации.

Ошибки опроса

Если задание, кажется, никогда не завершается, убедитесь, что при опросе вы используете идентификатор, фактически возвращённый в ответе на отправку, и читаете правильное поле статуса. Плотный цикл, игнорирующий статус failed, будет выглядеть как зависание. Добавьте жёсткий тайм-аут и логируйте наблюдаемые изменения статуса; этот лог обычно сразу раскрывает проблему.

Ловушки разбора ответа

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

Привычка быстрой диагностики

При возникновении проблемы сначала изолируйте уровень: запустите curl-команду с той же полезной нагрузкой. Если curl успешен, а Python падает, ошибка на стороне клиента; если падают оба, ошибка в запросе. Этот простой тест экономит больше времени, чем любая другая привычка отладки.

С рабочим вызовом и надёжным циклом опроса fibo-2.0/image-to-image становится стабильным шагом редактирования — начните со страницы модели на HiAPI и адаптируйте описанный выше запрос к своим собственным изображениям.

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

Все статьи →

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

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

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