Как пользоваться API Qwen Image 3.0? Китайский постер с первого раза и без ошибок

TL;DR

• Qwen Image 3.0 на HiAPI имеет 4 эндпоинта: стандартная версия qwen-image-3.0/text-to-image, qwen-image-3.0/image-to-image, Pro-версия qwen-image-3.0-pro/text-to-image, qwen-image-3.0-pro/image-to-image. Откройте страницу модели, чтобы попробовать онлайн.
• Стандартная версия — фиксированная цена $0.0358 за изображение (1K и 2K по одной цене); Pro 1K — $0.0497, 2K — $0.0993. Редактирование и генерация стоят одинаково, 1–3 референсных изображения не увеличивают стоимость.
• Сильная сторона — китайский и китайско-английский текст. Способ вызова: POST /v1/tasks с передачей prompt, aspect_ratio, resolution, затем опрос до статуса success и скачивание.

Сначала посмотрите одно изображение

Стандартная версия, 16:9, китайские иероглифы на вывеске написаны правильно, символ за символом:

qwen-image-3.0/text-to-image, 16:9, $0.0358.

Быстрый справочник параметров

Поле	Обязательно	Значения	Описание
prompt	Да	До 18000 символов	Текст, который должен появиться, впишите дословно в кавычках
aspect_ratio	Нет	1:1 (по умолчанию) 3:2 2:3 4:3 3:4 16:9 9:16 21:9
resolution	Нет	1K (по умолчанию) / 2K	В стандартной версии оба варианта по одной цене, в Pro 2K стоит вдвое дороже
output_format	Нет	png (по умолчанию) / jpeg
prompt_extend	Нет	Логическое значение, по умолчанию true	Автоматически переписывает промпт; отключите, если нужна точность текста
negative_prompt	Нет	До 500 символов	То, чего не должно быть на изображении
seed	Нет	0–2147483647	С фиксированным значением проще воспроизводить результат
image_urls	Обязательно для эндпоинта редактирования	1–3 изображения	JPEG, PNG, WEBP и т. д., каждое не более 10 MB

Параметры строго проверяются, передача лишнего поля возвращает 400. Обратите внимание: старый способ "model": "qwen-image-3.0" с size больше не работает — вернётся «модель недоступна» или additional properties 'size' not allowed. Используйте указанное выше имя модели и aspect_ratio + resolution.

curl: получите первое изображение

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-3.0/text-to-image",
    "input": {
      "prompt": "一张秋季饮品海报，中间是一杯桂花拿铁，顶部大标题逐字写“秋日限定”，下方副标题写“桂花拿铁”，留白充足，柔和自然光",
      "aspect_ratio": "3:4",
      "resolution": "2K",
      "prompt_extend": false
    }
  }'

В ответе будет data.taskId. Опрашивайте GET /v1/tasks/{taskId}, после того как status станет success, скачивайте по output[0].url. В стандартной версии 2K и 1K стоят одинаково — сразу запрашивайте 2K.

Python: сначала генерация, затем редактирование

# pip install requests; export HIAPI_KEY=ваш Key
import os, time, uuid, requests

API = "https://api.hiapi.ai/v1/tasks"
H = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def run(model, timeout_s=300, **inp):
    # При повторной отправке того же запроса используйте тот же Idempotency-Key — списание будет только один раз
    r = requests.post(API, json={"model": model, "input": inp},
                      headers={**H, "Idempotency-Key": str(uuid.uuid4())}, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{API}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] in ("fail", "failed"):
            raise RuntimeError(d)
        time.sleep(4)
    raise TimeoutError(task_id)

# Генерация по тексту, стандартная версия 2K ($0.0358)
poster = run("qwen-image-3.0/text-to-image",
             prompt="茶叶礼盒产品图，牛皮纸方盒正面写“云雾绿茶”，下方小字“净含量 100 克”，石板台面，柔和顶光",
             aspect_ratio="1:1", resolution="2K", prompt_extend=False)

# Редактирование: заменить на тёмный фон, текст не менять (те же $0.0358)
edited = run("qwen-image-3.0/image-to-image",
             prompt="保持礼盒和上面的文字完全不变，把背景换成深墨绿色绒布，加一缕侧光",
             image_urls=[poster], aspect_ratio="1:1", resolution="2K")

with open("tea.png", "wb") as f:
    f.write(requests.get(edited).content)

Чтобы перейти на Pro, измените только имя модели: qwen-image-3.0-pro/text-to-image или qwen-image-3.0-pro/image-to-image, параметры完全一样.

Сколько стоит

Эндпоинт	1K	2K
Стандартная версия: генерация / редактирование	$0.0358	$0.0358
Pro: генерация / редактирование	$0.0497	$0.0993

Текущие цены HiAPI, проверено 18 октября 2026 г. За неудачные запросы плата не взимается.

Сравнение двух версий с одинаковым промптом см. в Цены API Qwen Image 3.0.

Перед запуском в продакшен

• Отключайте prompt_extend, когда нужна точность текста: по умолчанию он переписывает ваш промпт и может заодно изменить нужные вам символы.
• Текст, который должен появиться, вписывайте дословно в кавычках и добавляйте фразу «кроме указанного текста,其他 текста нет».
• Используйте callback вместо опроса: на уровне input добавьте "callback": {"url": "https://your-app.example.com/hiapi/callback", "when": "final"}, дедуплицируйте по taskId.
• Добавляйте заголовок Idempotency-Key: при повторе один и тот же Key создаст задачу только один раз.
• Скачивайте результат сразу: у output[0].url есть срок действия.

Частые вопросы

Чем отличаются стандартная версия и Pro?

Параметры одинаковые, у Pro выше детализация изображения и плотность компоновки, 1K дороже примерно на 39%, 2K — вдвое. Китайский текст обе версии пишут точно.

Сколько изображений можно передать для редактирования?

1–3 изображения в image_urls, без доплаты.

Почему мой старый код возвращает «model not available»?

Старое имя модели qwen-image-3.0 выведено из эксплуатации, замените на qwen-image-3.0/text-to-image; параметр size также заменён на aspect_ratio и resolution.

Можно также сразу перейти на страницу модели и попробовать китайский постер.