Руководство
Как вызывать qwen-image-3.0-pro/image-to-image через HiAPI API: curl, Python и один рабочий запрос
Практическое руководство по интеграции: асинхронный шаблон задач, клиенты на curl и Python, а также обработка ошибок
На этой странице
Почему генерация изображения по изображению — это асинхронная задача
Когда вы вызываете модель генерации изображения по изображению, вы не запрашиваете строковое дополнение, которое можно вернуть потоком за несколько сотен миллисекунд. Модели нужно загрузить ваше исходное изображение, запустить полный процесс диффузионной генерации с ним в качестве условия и закодировать результат. Это может занять от нескольких секунд до десятков секунд, и время меняется в зависимости от разрешения и настроек. Держать HTTP-соединение открытым на всём этом промежутке невыгодно всем: прокси истекают по таймауту, балансировщики нагрузки отбрасывают простаивающие сокеты, а ваш собственный рабочий поток оказывается привязан к запросу, который может по-прежнему завершиться неудачей позже.
Поэтому этот эндпоинт использует модель «сначала отправить, затем опрашивать». Ваш первый запрос отправляет задачу и сразу возвращает дескриптор задачи. Генерация изображения происходит за этим дескриптором. Затем вы делаете отдельные недорогие запросы для проверки статуса задачи, пока она не сообщит о завершении, и в этот момент ответ будет содержать запрошенный результат.
Из этого следуют практические выводы, которые стоит заложить в дизайн с самого начала:
- Отправка — это не завершение. Успешный вызов отправки означает лишь то, что платформа приняла вашу задачу, и ничего больше. В коде различайте эти два состояния.
- ID задачи — ваш единственный дескриптор. Сохраняйте его. Если ваш процесс упадёт между отправкой и опросом, ID задачи станет тем, по чему можно восстановиться, не отправляя ту же работу заново (и не платя за неё второй раз).
- Опрос недорог, но не бесплатен. Проверки статуса легковесны, но частый цикл всё равно создаёт трафик и может вызвать ограничение скорости. Делайте интервалы.
- Сбои приходят асинхронно. Повреждённое изображение или отклонённые параметры могут появиться как ошибка уровня задачи, а не как HTTP-ошибка при отправке. Ваш код опроса должен читать статус задачи, а не только код состояния.
Держите эту модель в голове, и интеграция будет простой: один вызов создаёт работу, цикл ждёт её, и три возможных сценария отказа обрабатываются осознанно.
Перед написанием кода: что нужно подготовить
Прежде чем открывать терминал, соберите несколько вещей, на которых держится каждый вызов в этом руководстве.
Учётные данные HiAPI
Вам нужен API-ключ HiAPI. Относитесь к нему как к секрету: загружайте из переменной окружения, а не вставляйте в скрипт, который можете закоммитить. В примерах ниже он читается как HIAPI_API_KEY. Базовый URL API и точный идентификатор модели qwen-image-3.0-pro/image-to-image — две константы, на которые вы будете ссылаться повсюду.
Исходное изображение
Для генерации изображения по изображению нужен вход. Подготовьте его и решите, как его передавать:
- как публично доступный URL, или
- как загруженный ресурс или закодированные данные, в зависимости от того, какую форму принимает эндпоинт.
Прежде чем писать вызов, сверьтесь со схемой запроса модели, чтобы подтвердить точные имена полей и допустимые форматы исходного изображения. Передача исходного изображения, которое эндпоинт не принимает, — самая частая причина отклонения задачи, и исключить это заранее гораздо проще, чем отлаживать по сообщению об ошибке.
Клиент, способный опрашивать
Поскольку вызов асинхронный, инструмент, которым вы отправляете запрос, должен уметь повторно отправлять последующие запросы. curl подходит для первой проверки на работоспособность; для всего более долгосрочного лучше использовать скрипт. Нет ни URL обратного вызова, который нужно настраивать, ни webhook, который нужно размещать — механизмом является опрос, поэтому планируйте цикл.
Место, где посмотреть результат
Заранее решите, как для вас выглядит «готово»: URL, который можно открыть в браузере, или байты, которые вы записываете на диск. Если знать это заранее, то, что интеграция действительно работает, будет видно с первого взгляда.
Когда эти четыре вещи под рукой, первый запрос получается коротким.
Отправка одного рабочего запроса через curl
Самый быстрый способ убедиться, что ваш ключ, эндпоинт и жизненный цикл задачи работают, — это curl-сессия из двух шагов. Сначала отправьте; затем опрашивайте.
Шаг 1: отправка задачи
curl -sS -X POST "$HIAPI_BASE_URL/qwen-image-3.0-pro/image-to-image" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": "https://example.com/source.jpg",
"prompt": "restyle as a soft watercolor illustration"
}'
Разбор по частям:
-X POST— отправка является операцией создания.- Заголовок
Authorizationсодержит ваш ключ. Экспортируя переменную окружения вместо ввода в строке, вы не оставляете ключ в истории командной оболочки. Content-Type: application/json— тело запроса в формате JSON.-d— JSON-полезная нагрузка. Полеimageуказывает на ваше исходное изображение,promptописывает преобразование, которое нужно выполнить. Имена параметров и допустимые варианты берутся из схемы запроса модели; проверяйте там, а не угадывайте.
Ответ на успешную отправку — это объект задачи. Он содержит идентификатор — назовите его ID задачи — и поле статуса, которое должно показывать, что задача поставлена в очередь или выполняется. Запишите ID задачи; от него зависит всё дальнейшее.
Шаг 2: опрос задачи
export TASK_ID="<the id from the submit response>"
curl -sS "$HIAPI_BASE_URL/tasks/$TASK_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY"
При каждом вызове читайте поле статуса. Когда оно сообщает о состоянии ожидания или выполнения, подождите несколько секунд и проверьте снова. Когда оно сообщает об успехе, ответ содержит сгенерированное изображение — обычно это URL, по которому его можно получить, или закодированные данные. Когда оно сообщает о неудаче, ответ содержит описание ошибки с объяснением причины.
Весь жизненный цикл именно таков: одна отправка, затем проверки статуса до конечного состояния. Всё, что вы построите позже, — это лишь более удобная версия этих двух команд со ожиданием и обработкой ошибок.
Реализация того же вызова на Python
Повторять два шага curl вручную быстро надоедает, а копирование цикла опроса в каждый скрипт — именно так расползаются тонкие баги. Оберните шаблон отправки и опроса в переиспользуемую функцию.
import os
import time
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL_PATH = "/qwen-image-3.0-pro/image-to-image"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
def submit_task(source_image: str, prompt: str) -> str:
resp = requests.post(
BASE_URL + MODEL_PATH,
headers={**HEADERS, "Content-Type": "application/json"},
json={"image": source_image, "prompt": prompt},
timeout=30,
)
resp.raise_for_status()
return resp.json()["id"]
def wait_for_task(task_id: str, poll_interval: float = 3.0,
max_wait: float = 300.0) -> dict:
deadline = time.monotonic() + max_wait
while time.monotonic() < deadline:
resp = requests.get(
f"{BASE_URL}/tasks/{task_id}",
headers=HEADERS,
timeout=30,
)
resp.raise_for_status()
task = resp.json()
status = task["status"]
if status == "succeeded":
return task
if status == "failed":
raise RuntimeError(f"task {task_id} failed: {task.get('error')}")
time.sleep(poll_interval)
raise TimeoutError(f"task {task_id} did not finish within {max_wait}s")
def generate(source_image: str, prompt: str) -> dict:
task_id = submit_task(source_image, prompt)
return wait_for_task(task_id)
Стоит отметить несколько намеренных решений:
- Отправка отделена от ожидания. Если отправка не удалась, вы узнаете об этом до какого-либо опроса. Если позже вы захотите отправлять в одном процессе, а собирать в другом, шов уже есть.
- У каждого запроса есть
timeout. Запрос без таймаута может зависнуть на неопределённое время — именно тот режим отказа, от которого асинхронный API должен вас избавить. - В цикле опроса есть и интервал, и общий дедлайн. Без дедлайна задача, застрявшая в состоянии выполнения, будет зацикливаться вечно. Без интервала вы будете обрушивать эндпоинт запросами.
- Строки статуса сопоставляются явно. Любой статус, который не является ни успехом, ни неудачей, переходит к следующей итерации — это правильное поведение по умолчанию для промежуточных состояний.
Вызывайте её как любую функцию: generate(source_url, "make the background a dusk cityscape"). Возвращаемый объект — это полезная нагрузка задачи в конечном состоянии, из неё извлекайте ссылку на изображение.
Обработка ошибок и неудачных задач
Ошибки в асинхронных рабочих процессах делятся на три категории, и каждая требует своего ответа.
Отказ на уровне запроса
Это обычные HTTP-ответы об ошибке на вызов отправки — неверные или отсутствующие учётные данные, некорректный JSON, неподдерживаемые параметры, недоступное исходное изображение. Они приходят до того, как существует какая-либо задача.
Правильный ответ почти всегда — остановиться и показать сообщение. Повтор некорректной полезной нагрузки лишь тратит квоту и время. Записывайте код состояния и тело ответа дословно; сообщения валидации обычно указывают на проблемное поле. Два случая заслуживают особого обращения: сбои аутентификации должны происходить быстро и громко, потому что означают проблему конфигурации; ответы об ограничении скорости можно повторять после паузы.
Сбой на уровне задачи
Здесь отправка прошла успешно, ID задачи существует, но работа завершилась неудачей. Ответ на опрос сообщает статус неудачи вместе с ошибкой.
Эта категория охватывает проблемы самой модели: исходное изображение декодируется, но непригодно, промпт отклонён, генерация достигла внутреннего ограничения. Поскольку они специфичны для входных данных, слепой повтор обычно воспроизводит тот же сбой. Решайте по каждому случаю: временная внутренняя ошибка может стоить одного повтора; отклонённое исходное изображение не стоит никогда. Записывайте ID задачи вместе с ошибкой, чтобы связать её с запросом в поддержку.
Опрос, который никогда не заканчивается
Отправка прошла успешно, задача существует, опрос выполняется — но конечное состояние так и не наступает. Это не ошибка, возвращённая платформой; это предположение в вашем коде, у которого должен быть срок годности.
Защитите его дедлайном, как показано в примере на Python. Когда дедлайн срабатывает, прекратите опрос. Не возвращайте молча наполовину завершённый результат; выбросьте или верните явный результат таймаута, чтобы решение принял вызывающий код. Сохраните ID задачи — задача может всё ещё завершиться после вашего дедлайна, и вы можете захотеть забрать её позже без повторной отправки.
Практическое правило для этих трёх категорий: считайте статус задачи единственным источником истины. HTTP-код состояния говорит вам, был ли запрос принят; поле статуса и ошибки задачи говорит вам, была ли работа успешной. Читайте оба, и сбои становятся диагностируемыми, а не загадочными.
Обёртывание в производственный код
Функция выше — это работающая интеграция, а не готовый сервис. Прежде чем она будет нести реальный трафик, нужно укрепить четыре вещи.
Таймауты повсюду
Задавайте явные таймауты соединения и чтения для каждого вызова — отправки, опроса и любого последующего получения результирующего изображения. Затем задайте общий дедлайн для всего жизненного цикла задачи. Таймауты на уровне HTTP защищают отдельный запрос; дедлайн задачи защищает всю операцию.
Продуманные повторы
Повторяйте только то, что безопасно повторять. Ограничения скорости и временные сетевые ошибки при опросе подходят. Отклонённые полезные нагрузки — нет. Для сбоев на уровне задачи повтор означает отправку новой задачи, что является иной и более дорогой операцией, чем повтор проверки статуса — делайте это осознанным решением, лучше с ограничением.
Логи, включающие ID задачи
Записывайте ID задачи при отправке и при каждом последующем переходе состояния, вместе с временной информацией. Интервал между отправкой и первым конечным состоянием — это метрика, которая вам действительно понадобится, когда что-то покажется медленным. Когда пользователь сообщает о плохом результате, ID задачи — это ключ, превращающий рассказ в прослеживаемую запись.
Держите опрос вне пути запроса
Если ваша функция выполняется внутри веб-обработчика, синхронный цикл опроса будет держать запрос открытым на всё время генерации — именно та проблема, которую призван решить асинхронный дизайн. Вместо этого отправляйте в обработчике, возвращайте ID задачи вызывающему коду и выполняйте ожидание в фоновом рабочем процессе, очереди или запланированной задаче. Тогда клиент опрашивает ваш сервис, а не модель.
Построенная в этом порядке, интеграция превращается из «работает на моей машине» в то, на что можно положиться: отправьте, сохраните дескриптор, ждите с ограничениями, и пусть статус задачи — а не надежда — говорит вам, когда остановиться.
Похожие статьи
Все статьи →-
Руководство
Практическое руководство по gpt-6.2-sol: 5 ценных способов применения текстовой модели в бизнесе
-
Руководство
Практическое руководство по gpt-6.2-astra: интеграция и ключевые моменты реализации для 5 ценных текстовых сценариев
Чек-лист для разработчиков: от выбора сценариев до внедрения в инженерию
-
Руководство
Практические сценарии Tripo H3.1: 5 высокоценных применений и ключевые моменты реализации
От text-to-3D до multiview-восстановления: выбирайте правильный режим и параметры под бизнес-сценарий