Qwen Image Edit — краткое руководство по редактированию изображений с помощью текстовых инструкций

API Qwen Image Edit на платформе Novita AI изменяет существующее изображение по инструкции на естественном языке. В основе — модель Qwen-Image с 20 миллиардами параметров. Это краткое руководство охватывает полный асинхронный рабочий процесс: отправьте запрос на редактирование с исходным изображением и текстовой инструкцией, получите идентификатор задачи (task_id), опрашивайте сервер до завершения редактирования и получите URL готового изображения. Конечная точка — POST https://api.novita.ai/v3/async/qwen-image-edit.

Содержание

Когда использовать это руководство

Используйте это руководство, если вам нужно:

• Изменить существующее изображение с помощью текстовой инструкции — сменить фон, заменить стиль, удалить элементы, повернуть объекты или скорректировать одежду, не пересоздавая изображение с нуля.
• Сохранить нетронутые области нетронутыми при точечных правках. Двухканальная архитектура модели (Qwen2.5-VL для понимания семантики + VAE-энкодер для сохранения внешнего вида) специально спроектирована так, чтобы правки не «растекались» на области, которые вы не описывали.
• Точно редактировать текст на изображениях. Qwen Image Edit корректно заменяет двуязычные надписи (английский и китайский) на вывесках, плакатах и брендированных материалах — сохраняя шрифт, размер и окружающий визуальный стиль, что часто не удаётся другим генераторам изображений.

Если вы генерируете новое изображение только по текстовой инструкции (без входного изображения), используйте краткое руководство Qwen Image txt2img. Полный обзор возможностей модели, бенчмарков и архитектуры — в статье о запуске Qwen-Image на Novita AI.

Шаг 1. Получите API-ключ Novita

Создайте аккаунт Novita AI и перейдите в управление API-ключами. Сгенерируйте ключ и сохраните его как переменную окружения перед запуском любого из приведённых ниже примеров:

export NOVITA_API_KEY="ваш_api_ключ"

Не размещайте ключ в клиентском коде, сборках фронтенда и системах контроля версий. Если ключ скомпрометирован, отзовите его на той же странице настроек.

Шаг 2. Проверьте конечную точку и модель

Параметр	Значение
Конечная точка редактирования	POST https://api.novita.ai/v3/async/qwen-image-edit
Конечная точка опроса результата	GET https://api.novita.ai/v3/async/task-result?task_id=<id>
Модель	Qwen Image Edit (20B MMDiT, двухканальная архитектура)
Документация API	Справочник Qwen Image Edit от Novita AI

API асинхронный. Запрос на редактирование сразу возвращает task_id; вы опрашиваете конечную точку результата до получения статуса TASK_STATUS_SUCCEED. Это стандартный двухшаговый паттерн для всех конечных точек генерации изображений Novita AI, включая txt2img.

Цена — $0,02 за изображение. Перед построением модели затрат уточните текущий тариф на странице цен Novita AI.

Шаг 3. Отправьте первый запрос на редактирование

Выполните POST-запрос к конечной точке редактирования с исходным изображением и инструкцией:

curl -s -X POST https://api.novita.ai/v3/async/qwen-image-edit \
  -H "Authorization: Bearer $NOVITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Замени фон на горный пейзаж со снегом",
    "image": "https://example.com/my-portrait.jpg"
  }'

Успешный ответ с кодом 200 возвращает:

{
  "task_id": "abc123..."
}

Сохраните task_id — он понадобится для получения отредактированного изображения.

Шаг 4. Опрашивайте результат

Выполните GET-запрос к конечной точке результата, передав task_id как query-параметр:

curl -s "https://api.novita.ai/v3/async/task-result?task_id=abc123..." \
  -H "Authorization: Bearer $NOVITA_API_KEY"

Продолжайте опрос, пока поле task_status не станет TASK_STATUS_SUCCEED:

{
  "task_status": "TASK_STATUS_SUCCEED",
  "images": [
    {
      "image_url": "https://...",
      "image_url_ttl": "86400",
      "image_type": "JPEG"
    }
  ]
}

Срок действия image_url истекает по истечении TTL (обычно 24 часа). Скачайте и сохраните результат в своём объектном хранилище, если нужен долгосрочный доступ.

Значения статуса, которые нужно обрабатывать:

Статус	Значение
TASK_STATUS_QUEUED	Запрос в очереди; продолжайте опрос
TASK_STATUS_PROCESSING	Редактирование выполняется; продолжайте опрос
TASK_STATUS_SUCCEED	Завершено; получите отредактированное изображение из images[0].image_url
TASK_STATUS_FAILED	Генерация не удалась; проверьте поле error для выяснения причины

Шаг 5. Проверьте цены, лимиты и частые ошибки

Цена: $0,02 за изображение (уточняйте на странице цен).

Лимиты запросов: Проверьте справочник API для актуальных лимитов. При получении ошибки 429 снизьте частоту запросов и используйте экспоненциальную задержку при повторных попытках.

Распространённые HTTP-ошибки:

Код статуса	Вероятная причина
400	Некорректное тело запроса — отсутствует prompt или image, неверный формат изображения или неподдерживаемый размер
401	Отсутствует или недействителен API-ключ — проверьте формат Authorization: Bearer <ключ>
429	Превышен лимит запросов — добавьте задержку и логику повторных попыток
500	Ошибка на стороне сервера — повторите запрос после короткой паузы

Если статус задачи TASK_STATUS_FAILED, ответ обычно содержит сообщение об ошибке. Частые причины: неподдерживаемые форматы изображений, изображения, превышающие лимит размера, или запросы, срабатывающие фильтры безопасности контента.

Пример на Python

Этот скрипт отправляет запрос на редактирование, опрашивает до завершения и выводит URL итогового изображения:

import os
import time
import requests

API_KEY = os.environ["NOVITA_API_KEY"]
BASE_URL = "https://api.novita.ai/v3/async"


def submit_edit(image: str, prompt: str, seed: int | None = None) -> str:
    payload: dict = {"prompt": prompt, "image": image}
    if seed is not None:
        payload["seed"] = seed
    response = requests.post(
        f"{BASE_URL}/qwen-image-edit",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
    )
    response.raise_for_status()
    return response.json()["task_id"]


def poll_result(task_id: str, interval: float = 2.0, timeout: float = 120.0) -> dict:
    deadline = time.time() + timeout
    while time.time() < deadline:
        response = requests.get(
            f"{BASE_URL}/task-result",
            headers={"Authorization": f"Bearer {API_KEY}"},
            params={"task_id": task_id},
        )
        response.raise_for_status()
        data = response.json()
        status = data.get("task_status", "")
        if status == "TASK_STATUS_SUCCEED":
            return data
        if status == "TASK_STATUS_FAILED":
            raise RuntimeError(f"Edit task failed: {data}")
        time.sleep(interval)
    raise TimeoutError(f"Task {task_id} did not complete within {timeout}s")


if __name__ == "__main__":
    task_id = submit_edit(
        image="https://example.com/product-photo.jpg",
        prompt="Смени куртку на красную кожаную куртку, сохрани фон",
    )
    print(f"Task ID: {task_id}")

    result = poll_result(task_id)
    for img in result["images"]:
        print(img["image_url"])

Пример на cURL

Двухкомандный рабочий процесс с использованием jq для парсинга JSON:

#!/bin/bash
# Шаг 1: отправка запроса на редактирование
TASK_ID=$(curl -s -X POST https://api.novita.ai/v3/async/qwen-image-edit \
  -H "Authorization: Bearer $NOVITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Преобразуй в стиль акварельной живописи, сохрани объект и композицию",
    "image": "https://example.com/landscape.jpg"
  }' | jq -r '.task_id')

echo "Task ID: $TASK_ID"

# Шаг 2: опрос до завершения
while true; do
  RESULT=$(curl -s "https://api.novita.ai/v3/async/task-result?task_id=$TASK_ID" \
    -H "Authorization: Bearer $NOVITA_API_KEY")
  STATUS=$(echo "$RESULT" | jq -r '.task_status')
  echo "Status: $STATUS"
  if [ "$STATUS" = "TASK_STATUS_SUCCEED" ]; then
    echo "$RESULT" | jq -r '.images[].image_url'
    break
  elif [ "$STATUS" = "TASK_STATUS_FAILED" ]; then
    echo "Task failed:"
    echo "$RESULT" | jq .
    exit 1
  fi
  sleep 2
done

Установите jq с помощью apt install jq (Debian/Ubuntu) или brew install jq (macOS), если он ещё не установлен.

Ключевые параметры

Параметр	Тип	Обязательный	По умолчанию	Описание
prompt	string	Да	—	Инструкция на естественном языке, описывающая желаемое изменение
image	string	Да	—	Исходное изображение в виде URL или строки в кодировке base64
seed	integer	Нет	случайное	Фиксированный seed для воспроизводимых результатов при многократных запусках
output_format	string	Нет	jpeg	Выходной формат — обратитесь к документации API для допустимых значений

Как писать эффективные инструкции: Важна конкретность. «Замени текст на рекламном щите на „Summer Sale“» даёт модели чёткую ограниченную задачу. «Улучши изображение» — нет. Если нужно изменить один элемент, оставив всё остальное нетронутым, назовите то, что хотите сохранить: «Смени цвет куртки на красный, оставь фон и лицо без изменений». Это помогает каналу VAE-энкодера правильно зафиксировать нетронутые области.

Использование seed для итераций: При настройке инструкции фиксация seed позволяет напрямую сравнивать результаты редактирования — изменения будут связаны только с уточнением инструкции, а не со случайным сэмплированием. Когда вы найдёте работающую инструкцию, уберите seed, чтобы получить разнообразие результатов при многократном редактировании.

Типичные сценарии использования

Замена фона: «Замени фон на минималистичную белую студию» — Qwen Image Edit сохраняет контуры объекта и освещение, заменяя окружение. Надёжно работает, когда объект имеет чёткую границу с исходным фоном.

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

Смена стиля: «Преобразуй в стиль масляной живописи» или «сделай это похожим на карандашный рисунок» — применяется к исходному изображению, а не описывается с нуля. Канал VAE-энкодера сохраняет исходную композицию и расположение объектов, а инструкция управляет стилевым преобразованием.

Изменения на уровне объектов: Замена одежды, изменение цвета конкретных предметов, добавление или удаление аксессуаров. В инструкции следует назвать конкретный элемент, который изменяется, чтобы правка не затронула соседние области.

Преобразование IP и поворот объектов: Модель поддерживает изменение ракурса (например, поворот объекта для показа другого угла) и конвертацию между визуальными стилями для персонажей или товаров — сценарии описаны в обзоре Qwen-Image-Edit на Novita AI.

Устранение неполадок

Результат не изменился: Скорее всего, инструкция недостаточно конкретна. Сделайте более явным, какой элемент нужно изменить: «Смени цвет автомобиля с синего на красный» вместо «сделай его красным».

Правки распространились на нежелательные области: Для очень точных локальных правок включите в инструкцию явное указание сохранить остальное: «измени только X, оставь Y нетронутым». Слишком общие инструкции дают модели свободу переосмыслить всю композицию.

Задача завершена, но URL изображения возвращает 403 или 404: Поле image_url_ttl (в секундах) указывает, сколько времени действует URL. Если вы обращаетесь к нему позже, срок истёк. Скачайте изображение сразу после успешного опроса.

401 Unauthorized: Проверьте, что заголовок Authorization имеет точный формат Bearer <ключ> с пробелом после Bearer. Убедитесь, что ключ активен и не отозван в консоли Novita AI.

Задачи постоянно превышают тайм-аут: Редактирование изображений занимает больше времени, чем генерация текста — обычно 15–60 секунд при нормальной нагрузке. Если задачи стабильно превышают ваш тайм-аут, увеличьте окно опроса, прежде чем считать задачу неудачной.

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

Остаётся ли исходное изображение на серверах Novita?
Ваше изображение загружается на инфраструктуру Novita AI через HTTPS и обрабатывается на их серверах. Перед отправкой изображений, содержащих конфиденциальную личную информацию, медицинские данные или конфиденциальный контент, ознакомьтесь с политиками обработки данных Novita AI.

Можно ли использовать изображения в кодировке base64 вместо URL?
Да. Передайте сырую строку base64 в поле image. Обратитесь к документации API для получения информации о лимитах размера base64-полезной нагрузки.

Есть ли параметр seed для обеспечения консистентности?
Да — необязательный параметр seed фиксирует случайное состояние, так что одинаковые инструкция и изображение дают одинаковый результат. Полезно для итеративной подгонки формулировки без шума от повторного сэмплирования.

Можно ли использовать эту конечную точку для пакетной обработки?
Да. Отправляйте несколько запросов на редактирование параллельно и собирайте task_id, затем опрашивайте их одновременно. Каждый запрос независим.

В чём разница между этой конечной точкой и Qwen Image txt2img?
Конечная точка редактирования требует исходное изображение и создаёт его изменённую версию. Конечная точка txt2img генерирует изображение исключительно по текстовой инструкции — без входного изображения. Используйте редактирование, когда у вас есть существующий контент, который нужно изменить; используйте txt2img, когда создаёте с нуля.

Рекомендуемые статьи

• Qwen Image Text-to-Image — краткое руководство по генерации изображений из текста
• Qwen-Image-Edit на Novita AI: профессиональное редактирование всего за $0,02
• Novita AI теперь предлагает Qwen-Image: продвинутая модель текст-в-изображение на 20 млрд параметров