Как использовать Qwen Image 2.1 Turbo API: curl, Python и один реальный тестовый запрос

Qwen Image 2.1 Turbo (qwen-image-2.1-turbo) — это быстрый и недорогой уровень в линейке изображений 2.1 от Alibaba на hiapi. Он принимает текстовый промпт и опционально от 0 до 10 референсных изображений, а возвращает PNG 2048×2048. В этом руководстве приведены готовый к запуску запрос, входная схема, которую API фактически применяет, один вызов редактирования и результаты, которые мы увидели при проверке утверждения о «прозрачном PNG».

Вам понадобится API-ключ hiapi из консоли. Вызовы идут через единый асинхронный API задач, поэтому синхронного ответа с изображением нет.

Минимальный запрос: текст в изображение

curl -s -X POST https://www.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.1-turbo",
    "input": {
      "prompt": "иллюстрация в стиле стикера: сиба-ину в соломенной шляпе сидит на сёрфборде, плоская заливка, толстые контуры, кораллово-оранжевый и морской синий",
      "aspect_ratio": "1:1",
      "seed": 42
    }
  }'
# {"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

Затем опрашивайте GET /v1/tasks/<taskId>, пока data.status не станет success, и читайте data.output[0].url.

import os, time, requests

BASE = "https://www.hiapi.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def run(input_: dict) -> str:
    r = requests.post(f"{BASE}/v1/tasks", headers=HEADERS, timeout=30,
                      json={"model": "qwen-image-2.1-turbo", "input": input_})
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]          # внимание: поле называется taskId, а не id

    while True:
        try:
            d = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        except requests.RequestException:
            time.sleep(3)                          # временная сетевая ошибка: продолжаем опрашивать тот же id
            continue
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] in ("fail", "failed"):
            raise RuntimeError(d)
        time.sleep(3)                              # pending / running / archiving

url = run({"prompt": "a straw-hat shiba on a surfboard, flat sticker style", "aspect_ratio": "1:1"})
open("out.png", "wb").write(requests.get(url, timeout=60).content)

Скачивайте файл сразу. URL вывода находится на temp.hiapi.ai и содержит метку времени expireAt (в нашем запуске — примерно семь дней после создания); если нужно хранить дольше, сохраните байты файла самостоятельно.

Входная схема (правила, которые API фактически применяет)

Следующее взято из ошибок валидации, которые мы получили, намеренно отправляя недопустимые запросы, поэтому отражает реальное поведение живого эндпоинта, а не пересказ документации:

Поле	Правило
prompt	обязательная строка (форма на странице модели ограничивает её 4500 символами)
aspect_ratio	одно из значений 1:1, 16:9, 9:16, 4:3, 3:4
image_urls	массив URL референсных изображений, от 0 до 10 элементов; передача строки напрямую отклоняется с ошибкой image_urls must be an array
prompt_extend	логическое значение, переключатель оптимизации промпта
seed	целое число от 0 до 2147483647

Два момента отличаются от других моделей Qwen той же серии. Здесь нет поля resolution: отправка этого поля возвращает additional properties 'resolution' not allowed. Для 1:1 вывод — это фиксированный холст 2048×2048, что мы проверили на практике. Кроме того, неизвестные поля обычно отклоняются, а не игнорируются. Неверный aspect_ratio возвращает HTTP 400 с error_code: INVALID_REQUEST и перечислением допустимых значений в message.

Редактирование с референсными изображениями

Редактирование и перерисовка в другом стиле используют тот же id модели. Поместите исходное изображение в image_urls и опишите изменения в промпте:

curl -s -X POST https://www.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.1-turbo",
    "input": {
      "prompt": "перекрась соломенную шляпу в тёмно-фиолетовый, остальное оставь без изменений",
      "image_urls": ["https://temp.hiapi.ai/.../source.png"],
      "aspect_ratio": "1:1",
      "seed": 42
    }
  }'

Результаты, которые мы наблюдали в реальных запусках

Мы выполнили один вызов текст-в-изображение и один вызов редактирования 2026-10-24, оба с seed: 42 и aspect_ratio: "1:1".

• Задержка: генерация текст-в-изображение достигла success примерно через 29 секунд после создания (метки времени задачи created — completed); редактирование заняло около 22 секунд. Перед переходом в success статус несколько циклов опроса проходит через archiving, поэтому не считайте нетерминальное состояние ошибкой. Это лишь два образца, а не бенчмарк.
• Вывод: оба вернули PNG 2048×2048, результат текст-в-изображение весил около 3,9 МБ.
• Поведение редактирования: мы подали первый вывод обратно и попросили сделать шляпу фиолетовой. Результат сохранил собаку, позу, волны и композицию, а ленту и тесьму шляпы сместил в сторону фиолетового; соломенная основа шляпы в основном осталась соломенного цвета. Для изменения цвета на текстурированных объектах соблюдение инструкций при редактировании может быть лишь частичным, поэтому промпт следует писать конкретно (например, «перекрась тесьму шляпы»), а не описывать обобщённо.
• Прозрачный фон: альфа-канал полностью непрозрачен. Страница модели рекламирует вывод PNG с прозрачным фоном, и мы включили в промпт «полностью прозрачный фон, оставить только объект и эффект брызг». Возвращённый файл был в режиме RGBA, но альфа каждого пикселя равнялась 255 (ноль прозрачных пикселей), а углы были светло-серо-белыми (например, (241, 243, 248, 255)). При просмотре изображения обнаружилось, что модель нарисовала в пикселях слабый фон в стиле шахматной доски, а не оставила эти пиксели прозрачными. Результат редактирования показал то же самое (минимальная альфа 241). Таким образом, в нашем запуске только с помощью промпта не получилось готового к размещению на цветной странице вырезанного объекта. Этот результат соответствует лишь одному варианту промпта; мы не нашли поля запроса для переключения прозрачности (transparent отклоняется как неизвестное свойство). Если вам нужен настоящий альфа-канал, запланируйте шаг удаления фона, например, согласно руководству по API удаления фона 851-labs, и перед запуском в продакшен проверьте его пиксельной проверкой вроде Image.open(f).getchannel("A").getextrema().

Замечания для продакшена

• При высокой нагрузке используйте callback вместо опроса: добавьте в тело запроса задачи "callback": {"url": "https://your.app/hook", "when": "final"}, рассматривайте callback как подсказку, а затем подтверждайте результат через GET /v1/tasks/<taskId>.
• Сохраняйте taskId: если опрос прервался из-за сетевой ошибки, опрашивайте тот же id заново, а не отправляйте запрос повторно. Повторная отправка создаст и спишет оплату за вторую задачу.
• Фиксируйте seed, чтобы получать сопоставимые результаты при настройке промпта; рассматривайте это как наилучшее усилие, а не жёсткую гарантию.
• Сначала валидация, потом оплата: ошибки схемы (HTTP 400, INVALID_REQUEST) возвращаются при создании, когда ещё не сгенерировано ни одного изображения.

Какой уровень выбрать

В той же серии есть Qwen Image 2.1 Pro, у которого указанная на странице цен цена за изображение выше, чем у Turbo. Оба описаны как поддерживающие текст-в-изображение, редактирование и от 0 до 10 референсных изображений; мы запускали только Turbo, поэтому не делаем никаких утверждений об относительном качестве изображений. Преимущество Turbo — более низкая цена и скорость в 8 шагов; если для ваших материалов важнее качество вывода, запустите оба с одинаковым промптом и seed и сравните. О более новом поколении Qwen 3.0 см. руководство по API Qwen Image 3.0 и руководство по Qwen Image 3.0 Pro.

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

• Страница модели Qwen Image 2.1 Turbo
• Цены
• Руководство по API Qwen Image 3.0
• Документация

Часто задаваемые вопросы

Какой id модели? qwen-image-2.1-turbo, отправляется через POST /v1/tasks.

Можно ли выбрать разрешение вывода? В этой схеме нет: поля resolution не существует. Выберите одно из пяти допустимых значений aspect_ratio.

Поддерживается ли редактирование? Да: передайте от 1 до 10 исходных изображений в image_urls вместе с промптом-инструкцией. В наших тестах изменение цвета на текстурированных областях срабатывало лишь частично.

Возвращается ли прозрачный PNG? В наших тестах нет: файл в режиме RGBA, но альфа-канал полностью непрозрачен и содержит нарисованный фон. Проверяйте альфу самостоятельно и, если нужна настоящая прозрачность, добавляйте шаг удаления фона.

Сколько это стоит? См. страницу цен; на момент написания это более дешёвый из двух уровней 2.1.