Qwen Image 2.1

Создавайте или редактируйте изображение в 1K или 2K по тексту и с использованием до 10 референсных изображений. При необходимости результат можно получить в PNG или WebP с прозрачным фоном.

• Асинхронная обработка: запрос создания быстро возвращает ID задачи. Изображение будет доступно после её успешного завершения.
• Одна задача создаёт одно изображение. Для нескольких изображений создайте несколько задач.
• Генерация по тексту либо редактирование и объединение до 10 референсных изображений по общедоступным HTTPS-ссылкам.
• Для прозрачного фона задайте background: "transparent" и output_format со значением png или webp. JPEG не поддерживает прозрачность.
• Переписывание промпта (enhance_prompt) по умолчанию включено для генерации по тексту и выключено для редактирования, если вы не указали иначе.
• Цена за изображение зависит от resolution — 1K или 2K. Задача, завершившаяся ошибкой, не оплачивается.

Открывает модель в API Explorer. Введите свой API-ключ BeatAPI, чтобы создать задачу. Это настоящий запрос: его стоимость спишется с вашего баланса.

Адрес API и авторизация

POST https://api.beatapi.io/v1/images/tasks

Передавайте тело запроса в JSON с заголовком Content-Type: application/json. Idempotency-Key необязателен. Для каждого логического запроса используйте уникальное значение длиной не более 255 символов и повторно используйте его только для отправки точно такого же тела. В течение 24 часов повтор с тем же ключом и телом возвращает первый ответ с заголовком Idempotent-Replayed: true. Тот же ключ с другим телом возвращает 409 idempotency_conflict. Ответы, отличные от 2xx, не сохраняются, поэтому повтор после 400 или 402 выполняется заново.

Как выполняется запрос

Режимы ввода

Параметры запроса

"images": [
  "https://cdn.beatapi.io/samples/smart-bottle.png"
]

Перед созданием задачи шлюз также проверяет следующие сочетания параметров:

• aspect_ratio: auto сохраняет пропорции первого изображения; без изображений создаётся 1:1.
• enhance_prompt переписывает промпт перед генерацией. Без изображений по умолчанию включён, с изображениями — выключен: при редактировании переписывание может потерять указание, что сохранить.
• background: transparent требует output_format со значением png или webp.

Ограничения входных материалов

До создания задачи шлюз проверяет каждый входной материал. Если ограничение нарушено, возвращается 400 bad_request с указанием материала. Средства не списываются.

• Референсные изображения: PNG, JPEG или WebP с определением формата по содержимому, а не имени файла или Content-Type; до 50 MB каждый (десятичные мегабайты; проверяется, если сервер сообщает размер), от 1 до 10 ссылок. GIF, HEIC и SVG отклоняются.
• Для этой модели ограничения числа пикселей и соотношения сторон не проверяются.
• Если сервер не ответил вовремя, ссылка не отклоняется при создании. Если скачать её не удастся и позже, задача завершится ошибкой с возвратом средств.
• Файл находится на вашем устройстве? Загрузите его через POST /v1/files и передайте полученный data.url.

Параметры, которые модель не принимает

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

• quality, size → field "quality" is not supported by model qwen-image-2.1 (с именем переданного поля).
• Любое другое неизвестное поле, например n → unknown field: n. Поля n нет: одна задача создаёт одно изображение.

Если неверных полей несколько, сообщение указывает только одно. Исправьте его и повторите запрос.

Прозрачные изображения

Передайте "background": "transparent" и output_format со значением png или webp. У JPEG нет альфа-канала, поэтому transparent вместе с jpeg отклоняется при создании, до резервирования средств. Одного упоминания прозрачного фона в промпте недостаточно для установки background.

BeatAPI не конвертирует в WebP или из него. Фактический формат проверяйте в output.media[].mime_type завершённой задачи.

Примеры запросов

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "qwen-image-2.1",
  "prompt": "A white porcelain crane above misty mountains, ink-wash style, no text"
}'

Изображение по тексту

Изображение в 1K по промпту со значениями по умолчанию: aspect_ratio со значением auto даёт 1:1, переписывание промпта включено.

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "qwen-image-2.1",
  "prompt": "A white porcelain crane above misty mountains, ink-wash style, no text"
}'

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

Для редактирования переписывание по умолчанию выключено, поэтому указание сохранить бутылку передаётся без изменений. auto сохраняет пропорции референса.

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "qwen-image-2.1",
  "prompt": "Keep the bottle shape and label exactly as they are. Place it on a pale stone counter under soft morning light.",
  "images": [
    "https://cdn.beatapi.io/samples/smart-bottle.png"
  ],
  "aspect_ratio": "auto"
}'

Прозрачный WebP

Отдельный объект на прозрачном фоне, в 2K.

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "qwen-image-2.1",
  "prompt": "A single green glass perfume bottle, isolated, studio lighting, no text",
  "resolution": "2K",
  "aspect_ratio": "1:1",
  "background": "transparent",
  "output_format": "webp"
}'

Воспроизводимый запрос

Фиксированный seed с выключенным переписыванием промпта для сравнения небольших изменений текста.

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "qwen-image-2.1",
  "prompt": "A lighthouse on a cliff at dawn, flat illustration, limited palette",
  "aspect_ratio": "3:4",
  "enhance_prompt": false,
  "seed": 42
}'

Ответы

Создание задачи (201)

Объект задачи. Поле output равно null, пока задача не завершится успешно. Поля с пометкой «во время выполнения» исчезают после завершения задачи.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "image",
    "capability_id": "qwen-image-2.1",
    "capability_version": 1,
    "media_type": "image",
    "model": "qwen-image-2.1",
    "status": "queued",
    "stage": "queued",
    "created_at": 1791993600,
    "updated_at": 1791993600,
    "completed_at": null,
    "poll_after_seconds": 5,
    "output": null,
    "usage": {
      "credits_reserved": 0.03,
      "credits_settled": 0,
      "credits_refunded": 0,
      "credits_charged": 0.03
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

Успешно завершённая задача

GET /v1/tasks/{task_id} возвращает HTTP 200 со status: "succeeded" и результатом в data.output.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "image",
    "capability_id": "qwen-image-2.1",
    "capability_version": 1,
    "media_type": "image",
    "model": "qwen-image-2.1",
    "status": "succeeded",
    "stage": "succeeded",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": {
      "media": [
        {
          "type": "image",
          "url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.png",
          "mime_type": "image/png"
        }
      ],
      "r2_url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.png"
    },
    "usage": {
      "credits_reserved": 0.03,
      "credits_settled": 0.03,
      "credits_refunded": 0,
      "credits_charged": 0.03
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

Поля результата

Задача, завершившаяся ошибкой

Если задача завершилась ошибкой, GET /v1/tasks/{task_id} всё равно возвращает HTTP 200: сведения об ошибке находятся в теле ответа. Зарезервированная сумма возвращается полностью, поэтому списания нет.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "image",
    "capability_id": "qwen-image-2.1",
    "capability_version": 1,
    "media_type": "image",
    "model": "qwen-image-2.1",
    "status": "failed",
    "stage": "failed",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": null,
    "usage": {
      "credits_reserved": 0.03,
      "credits_settled": 0,
      "credits_refunded": 0.03,
      "credits_charged": 0
    },
    "retryable": true,
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": "processing_failed",
    "error_message": "The task failed during processing on our side. Retry; a failed task is refunded."
  }
}

Полный пример

Создайте задачу, дождитесь её завершения с интервалом опроса, указанным сервером, и выведите ссылки на результаты. Задайте BEATAPI_API_KEY в переменной окружения и установите requests.

import os
import time
import uuid
import requests
API = "https://api.beatapi.io"
HEADERS = {"Authorization": f"Bearer {os.environ['BEATAPI_API_KEY']}"}
def create_task(body: dict) -> dict:
    # One Idempotency-Key per logical request: a retry with the same key cannot create a second task.
    headers = {**HEADERS, "Idempotency-Key": str(uuid.uuid4())}
    for attempt in range(3):
        response = requests.post(f"{API}/v1/images/tasks", headers=headers, json=body, timeout=60)
        if response.status_code in (429, 503) and attempt < 2:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        break
    try:
        payload = response.json()
    except ValueError:  # an edge error page is not JSON
        response.raise_for_status()
        raise
    if not response.ok:
        error = payload["error"]
        raise RuntimeError(f"{response.status_code} {error['code']}: {error['message']} (request_id={error.get('request_id')})")
    return payload["data"]
def wait_for_task(task_id: str, timeout_seconds: int = 1800) -> dict:
    deadline = time.monotonic() + timeout_seconds
    while time.monotonic() < deadline:
        response = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
        if response.status_code == 429 or response.status_code >= 500:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        response.raise_for_status()
        task = response.json()["data"]
        if task["status"] in ("succeeded", "failed"):
            return task
        time.sleep(task.get("poll_after_seconds", 5))
    raise TimeoutError(f"task {task_id} is still running; keep polling later")
task = create_task({
  "model": "qwen-image-2.1",
  "prompt": "A white porcelain crane above misty mountains, ink-wash style, no text"
})
print("created", task["id"])
task = wait_for_task(task["id"])
if task["status"] == "failed":
    raise SystemExit(f"{task['error_code']}: {task['error_message']}")
for item in task["output"]["media"]:
    print(item["url"])

Оплата

• Одна задача создаёт одно изображение с ценой по resolution, см. таблицу ниже. В прайс-листе отдельная строка для каждого разрешения, без доплаты за референсные изображения, прозрачность или переписывание промпта.
• Стоимость резервируется при создании задачи на балансе и в лимите ключа, если он установлен. Запрос, отклонённый до создания задачи, не оплачивается.
• При успешном завершении резерв списывается. При ошибке возвращается полностью: credits_refunded равно credits_reserved, а credits_charged и credits_settled равны 0.

Текущие базовые цены совпадают с указанными на странице цен. Если для аккаунта согласована скидка, стоимость будет ниже. Фактически списанная сумма всегда указана в data.usage задачи.

Частые ошибки

Краткий справочник HTTP-ошибок

Ошибки до создания задачи возвращаются с HTTP-статусом, отличным от 2xx, без списания средств. Обрабатывайте error.code или error.retryable; причина указана в message. Полный список и правила повторов приведены в разделе ошибок.

{
  "error": {
    "code": "bad_request",
    "message": "\"prompt\" is required",
    "retryable": false,
    "request_id": "req_5f0c2a9e4b7d4e31"
  }
}