Руководство
Как вызывать fibo-edit-1.5 для редактирования изображений через HiAPI API: руководство по curl и Python
Практическое руководство по рабочим запросам для редактирования изображений на основе инструкций
На этой странице
Что умеет эндпоинт редактирования изображений fibo-edit-1.5
fibo-edit-1.5/image-to-image — это эндпоинт редактирования изображений, управляемый инструкциями. Он не описывает сцену с нуля, а принимает опорное изображение и инструкцию на естественном языке, возвращая новое изображение, к которому применено это редактирование при сохранении остальной композиции без изменений.
Такая трактовка напрямую влияет на то, как вы проектируете запрос. Опорное изображение несёт визуальный контекст — объект, кадрирование, освещение, стиль — а инструкция несёт изменения. Хорошая инструкция явно указывает, что нужно изменить, и молчит о том, что должно остаться прежним. «Замени небо на мягкий закатный градиент, сохрани здание и передний план без изменений» сообщает гораздо больше, чем «сделай красивее».
Успешный вызов создаёт отредактированный ресурс изображения. В зависимости от способа вызова эндпоинта ответ будет содержать сгенерированный результат в форме, которую вы можете сохранить или получить — обратитесь к справочнику по эндпоинту, чтобы узнать точную структуру ответа и поддерживаемые параметры. Считайте этот справочник единственным авторитетным источником по именам полей, допустимым форматам изображений и ограничениям по размеру, поскольку эти детали могут развиваться независимо от данного документа.
Типичные варианты использования включают ретушь продуктовых фотографий, замену фона, корректировку стиля и локальное редактирование, при котором полная регенерация изображения привела бы к потере точности. Если ваша задача состоит только в генерации по тексту, а не в редактировании, то этот эндпоинт не подходит; используйте модель текст-в-изображение.
Одно ожидание, которое стоит установить сразу: редактирование по своей природе итеративно. Ваша первая инструкция редко срабатывает идеально, поэтому стройте рабочий процесс вокруг дешёвых итераций — меняйте по одному параметру за раз, сохраняйте опорное изображение неизменным и сравнивайте результаты перед переходом к следующему шагу.
Из чего состоит рабочий запрос
Прежде чем писать какой-либо код, разберитесь, какие входные данные нужны одному запросу. Каждый вызов fibo-edit-1.5/image-to-image объединяет четыре категории информации.
Аутентификация
Все запросы проходят через единый интерфейс HiAPI и несут ваш API-ключ в заголовке Authorization. Храните ключ в переменной окружения, а не в исходном коде, и никогда не коммитьте его.
Опорное изображение
Вам нужно предоставить исходное изображение, к которому применяется редактирование. Есть две распространённые формы: публичный URL, который может получить сервис, или данные в кодировке base64, встроенные в тело JSON-запроса. URL удобнее для итераций; base64 избавляет от зависимости от внешнего хостинга. Обратитесь к справочнику по эндпоинту, чтобы узнать, какие формы принимаются и какие есть ограничения по размеру или разрешению.
Инструкция редактирования
Это строка на естественном языке, описывающая изменение. Пишите её в повелительном наклонении, указывайте область или элемент для изменения и описывайте, что следует сохранить. Избегайте складывать несколько несвязанных правок в одну инструкцию — разделяйте их на отдельные вызовы, чтобы можно было определить, какая из них привела к плохому результату.
Управление выводом
Необязательные параметры, такие как размер, формат вывода или количество вариантов изображения. При первом вызове оставьте значения по умолчанию, а затем меняйте их осознанно. Каждый заданный вами параметр — это ещё одна переменная, которую нужно исключить при возникновении проблем.
Таким образом, минимальное тело запроса содержит два существенных поля — изображение и инструкцию — упакованных в JSON-объект, необязательно с вашими предпочтениями по выводу. Если вы можете ответить на вопрос «какое изображение, какое изменение, в каком формате я хочу получить результат», то у вас есть всё необходимое для написания этого вызова.
Вызов через curl
Начните с curl: он изолирует HTTP-уровень, поэтому при возникновении проблемы вы будете знать, что дело в запросе, а не в коде приложения.
Сначала экспортируйте ваш ключ:
export HIAPI_API_KEY="your-api-key"
Затем отправьте JSON-тело запроса с URL опорного изображения и инструкцией:
curl -sS https://api.hiapi.ai/v1/fibo-edit-1.5/image-to-image \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": "https://example.com/input.jpg",
"prompt": "Замени плоское небо на мягкий закатный градиент; сохрани здание и передний план без изменений."
}'
Несколько практических советов:
- Сверьте базовый URL и путь со справочником по эндпоинту, не копируйте их по памяти.
- Используйте
-sS, чтобы curl молчал при успехе, но всё же показывал ошибки передачи. - Если вы не хотите зависеть от внешнего хостинга, закодируйте файл в base64 и замените значение
imageна закодированную строку, соблюдая имя поля, указанное в справочнике. - На этапе исследования пропускайте вывод через
jq ., чтобы ответ было легче читать.
Чтобы подтвердить ответ, найдите возвращённые данные изображения или URL и откройте его. Если тело ответа содержит объект ошибки, запишите его поля type и message — они подскажут, в чём проблема: в изображении, инструкции или структуре запроса. Сохраните успешный сырой ответ в файл; он станет вашей тестовой фикстурой при написании Python-клиента и доказательством при будущих изменениях поведения.
Тот же запрос на Python
Версия на Python должна в точности соответствовать вызову curl — тот же путь, те же заголовки, то же тело — чтобы любое расхождение было ошибкой в вашем коде, а не различием в том, что вы запрашиваете.
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/fibo-edit-1.5/image-to-image"
payload = {
"image": "https://example.com/input.jpg",
"prompt": (
"Замени плоское небо на мягкий закатный градиент; "
"сохрани здание и передний план без изменений."
),
}
response = requests.post(
URL,
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=120,
)
response.raise_for_status()
result = response.json()
print(result)
Отправка локального файла
Если вы редактируете файл на диске, закодируйте его и отправьте строку вместо URL:
import base64
with open("input.jpg", "rb") as f:
encoded = base64.b64encode(f.read()).decode("utf-8")
payload = {
"image": encoded,
"prompt": "Замени фон на чистый нейтрально-серый; сохрани продукт чётким.",
}
Прежде чем полагаться на этот способ, проверьте точное имя поля и ожидаемую кодировку в справочнике по эндпоинту.
Сохранение вывода
Записывайте возвращённое изображение на диск, чтобы вы могли сравнивать результаты итераций бок о бок и отслеживать, какая инструкция дала какой результат. Небольшая вспомогательная функция, сохраняющая вывод под именем, производным от хеша инструкции, сделает последующие сравнения очень простыми.
Обязательно задавайте явный timeout. Редактирование изображений занимает больше времени, чем простой текстовый вызов, а запрос без тайм-аута при сетевом зависании будет бесконечно держать рабочий процесс.
Обработка ошибок и безопасные повторные попытки
Сбои делятся на несколько крупных категорий, и каждая требует разного подхода.
Ошибки клиента
Проблема в самом запросе: неверный JSON, отсутствующее поле изображения, неподдерживаемый формат изображения, инструкция, которую модель не может выполнить, или проблемы с аутентификацией. Повторять такие ошибки как есть — пустая трата времени и квоты, они будут повторяться одинаково. Вместо этого исправьте запрос. При возникновении таких ошибок записывайте полное тело запроса (с усечённой частью изображения) и сообщение об ошибке, затем исправляйте входные данные.
Ограничения частоты
Вы отправляете запросы быстрее, чем позволяет разрешённая квота. Правильная реакция — отступить и повторить попытку, а не бить по эндпоинту. Следуйте любым подсказкам о повторной попытке, предоставленным в ответе; в противном случае используйте экспоненциальную задержку.
Серверные и временные ошибки
Тайм-ауты, сбросы соединения и сбои восходящего потока заслуживают повторной попытки. Именно здесь пригодится логика идемпотентных повторных попыток.
Практическая стратегия повторных попыток
- Повторяйте попытку только при тайм-аутах, ошибках соединения, а также ответах об ограничении частоты или серверных ошибках.
- Используйте экспоненциальную задержку с верхним пределом — например, начинайте с короткой задержки, удваивайте её при каждой попытке и останавливайтесь после небольшого фиксированного числа попыток.
- Добавляйте джиттер к задержке, чтобы параллельные рабочие процессы не повторяли попытку все в один момент.
- Никогда не повторяйте запросы, отклонённые из-за схемы, формата или инструкции.
- Записывайте каждую попытку с её номером и результатом, чтобы видеть, не концентрируются ли сбои.
import random, time, requests
def edit_with_retry(payload, attempts=4):
delay = 1.0
for i in range(attempts):
try:
r = requests.post(URL, headers=HEADERS, json=payload, timeout=120)
except (requests.Timeout, requests.ConnectionError):
pass
else:
if r.status_code < 400:
return r.json()
if r.status_code not in (429, 500, 502, 503, 504):
r.raise_for_status()
time.sleep(delay + random.uniform(0, 0.5))
delay = min(delay * 2, 30)
raise RuntimeError("Редактирование не удалось после повторных попыток")
Считайте это каркасом: согласуйте повторяемые коды состояния с тем, что фактически возвращает эндпоинт, и централизуйте стратегию в одном месте, чтобы её использовали все вызывающие стороны.
Проверка перед запуском в продакшен
Прежде чем подключать эндпоинт к продакшену, выполните краткий контрольный список.
Дважды проверьте нормальный путь
Повторно запустите сохранённый вызов curl и Python-клиент с одинаковыми входными данными и убедитесь, что они дают эквивалентные результаты. Если они расходятся, значит, ваши тела запросов на самом деле не идентичны.
Откалибруйте инструкции на реальных входных данных
Тестируйте свои инструкции на репрезентативных изображениях, а не только на одном образце. Качество редактирования во многом зависит от конкретности инструкции и от того, насколько опорное изображение поддерживает это изменение. Храните небольшой набор пар «подсказка-вывод» в качестве набора регрессионных тестов; когда вы меняете формулировку, вы сможете увидеть, что улучшилось, а что ухудшилось.
Проверьте ограничения и форматы
В справочнике по эндпоинту уточните допустимые форматы изображений, максимальный размер и любые ограничения на размер запроса. Выполняйте локальную проверку перед отправкой — отклонить плохое изображение на клиенте быстрее и дешевле, чем делать сетевой запрос.
Проверьте ключи и журналы
Убедитесь, что API-ключ берётся из переменной окружения, что журналы запросов усекают данные изображения и что никакие ключи не попадают в отчёты об ошибках.
Подтвердите поведение при сбое
В пре-продакшен среде принудительно вызовите тайм-аут и некорректное тело запроса, проверьте, что ваша стратегия повторных попыток ведёт себя правильно и что постоянные сбои доходят до вызывающей стороны, а не исчезают бесследно.
Как только всё это пройдёт, интеграция станет скучной — и это к лучшему. Получите авторитетный список параметров из справочника по эндпоинту редактирования изображений fibo-edit-1.5, а затем двигайтесь от рабочего вызова curl наружу.
Похожие статьи
Все статьи →-
Руководство
Практическое руководство по gpt-6.2-sol: 5 ценных способов применения текстовой модели в бизнесе
-
Руководство
Практическое руководство по gpt-6.2-astra: интеграция и ключевые моменты реализации для 5 ценных текстовых сценариев
Чек-лист для разработчиков: от выбора сценариев до внедрения в инженерию
-
Руководство
Практические сценарии Tripo H3.1: 5 высокоценных применений и ключевые моменты реализации
От text-to-3D до multiview-восстановления: выбирайте правильный режим и параметры под бизнес-сценарий