- Когда использовать это краткое руководство
- Шаг 1. Получите ключ API Novita
- Шаг 2. Проверьте эндпоинт и модель
- Шаг 3. Отправьте первый запрос
- Шаг 4. Опрос результата
- Пример на Python: полный цикл
- Пример cURL
- Ключевые параметры
- Что Qwen Image генерирует хорошо
- Частые ошибки и их устранение
- FAQ
- Рекомендуемые статьи
API Qwen Image text-to-image на Novita AI генерирует изображения по текстовым запросам с помощью модели Qwen Image 20B — той же основы, которая обеспечивает работу Qwen Image Edit API для точного редактирования. Это краткое руководство охватывает полный асинхронный рабочий процесс: отправка запроса на генерацию, получение ID задачи, опрос до завершения и получение URL изображения. Эндпоинт — POST https://api.novita.ai/v3/async/qwen-image-txt2img.
Когда использовать это краткое руководство
Используйте это руководство, когда вам нужно:
- Генерировать изображения из текстовых запросов с высококачественным рендерингом текста на английском или китайском языке через
POST /v3/async/qwen-image-txt2img. - Создавать конвейеры для генерации плакатов, графических материалов или иллюстрированного контента, где важна читаемость текста внутри изображения.
- Быстро прототипировать с использованием облачного API вместо запуска модели 20B на локальной GPU-инфраструктуре.
Модель Qwen Image особенно сильна в генерации изображений с читаемым стилизованным текстом — представьте плакаты, вывески, макеты продуктов и обложки. Если ваш сценарий связан с редактированием существующего изображения, а не с генерацией с нуля, обратитесь к Qwen Image Edit API. Если вам нужен полный обзор возможностей и бенчмарков модели Qwen Image, в анонсе Qwen Image от Novita AI подробно описаны архитектура и результаты тестов.
Шаг 1. Получите ключ API Novita
Создайте аккаунт Novita AI и перейдите в раздел управления ключами API. Сгенерируйте ключ и сохраните его как переменную окружения:
export NOVITA_API_KEY="your_api_key_here"
Не храните ключ в клиентском коде, фронтенд-сборках и системах контроля версий.
Шаг 2. Проверьте эндпоинт и модель
| Элемент | Значение |
|---|---|
| Эндпоинт генерации | POST https://api.novita.ai/v3/async/qwen-image-txt2img |
| Эндпоинт опроса результата | GET https://api.novita.ai/v3/async/task-result?task_id=<id> |
| Модель | Qwen Image (20B MMDiT) |
| Документация API | Справка Novita AI Qwen Image txt2img |
API использует двухэтапный асинхронный паттерн, общий для всех эндпоинтов генерации изображений Novita AI. Вызов генерации возвращает только task_id; отдельно вы опрашиваете эндпоинт результата, пока задача не завершится.
Стоимость составляет $0.02 за изображение — как и для эндпоинта Qwen Image Edit. Проверьте актуальный тариф на странице цен Novita AI, прежде чем составлять смету.
Шаг 3. Отправьте первый запрос
Отправьте POST-запрос на эндпоинт генерации с параметром prompt и необязательным параметром size:
curl -s -X POST https://api.novita.ai/v3/async/qwen-image-txt2img \
-H "Authorization: Bearer $NOVITA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A cinematic mountain landscape at sunrise, warm golden light, ultra-detailed, 8K",
"size": "1024*1024"
}'
Успешный ответ с кодом 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"
Ответ содержит поле status. Продолжайте опрос, пока статус не станет TASK_STATUS_SUCCEED:
{
"task": {
"task_id": "abc123...",
"status": "TASK_STATUS_SUCCEED"
},
"images": [
{
"image_url": "https://...",
"image_url_ttl": "3600",
"image_type": "png"
}
]
}
image_url — это URL с ограниченным сроком действия; значение image_url_ttl (в секундах) показывает, сколько времени он остается валидным. Скачайте изображение сразу или проксируйте его через собственное хранилище, если нужен долгосрочный доступ.
Статусы, которые нужно обрабатывать:
| Статус | Значение |
|---|---|
TASK_STATUS_QUEUED |
Запрос в очереди, еще не начат |
TASK_STATUS_PROCESSING |
Генерация выполняется |
TASK_STATUS_SUCCEED |
Изображение готово; возьмите images[0].image_url |
TASK_STATUS_FAILED |
Генерация не удалась; проверьте task.reason |
Пример на Python: полный цикл
Скрипт отправляет запрос на генерацию, опрашивает сервер до завершения и выводит URL изображения.
import os
import time
import requests
API_KEY = os.environ["NOVITA_API_KEY"]
BASE_URL = "https://api.novita.ai"
def generate_image(prompt: str, size: str = "1024*1024") -> str:
response = requests.post(
f"{BASE_URL}/v3/async/qwen-image-txt2img",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json={"prompt": prompt, "size": size},
)
response.raise_for_status()
return response.json()["task_id"]
def poll_result(task_id: str, interval: float = 2.0, max_attempts: int = 60) -> str:
for _ in range(max_attempts):
response = requests.get(
f"{BASE_URL}/v3/async/task-result",
headers={"Authorization": f"Bearer {API_KEY}"},
params={"task_id": task_id},
)
response.raise_for_status()
data = response.json()
status = data["task"]["status"]
if status == "TASK_STATUS_SUCCEED":
return data["images"][0]["image_url"]
elif status == "TASK_STATUS_FAILED":
reason = data["task"].get("reason", "unknown")
raise RuntimeError(f"Generation failed: {reason}")
time.sleep(interval)
raise TimeoutError(f"Task {task_id} did not complete after {max_attempts} polls")
if __name__ == "__main__":
prompt = (
"A poster reading 'Welcome to Novita AI' in bold neon letters "
"against a dark city skyline at night, cinematic lighting"
)
task_id = generate_image(prompt, size="1024*1024")
print(f"Task ID: {task_id}")
image_url = poll_result(task_id)
print(f"Image URL: {image_url}")
Пример cURL
Схема из двух команд для полного рабочего процесса:
# Step 1: Submit generation request
TASK_ID=$(curl -s -X POST https://api.novita.ai/v3/async/qwen-image-txt2img \
-H "Authorization: Bearer $NOVITA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A serene Japanese garden with cherry blossoms, koi pond, morning mist, watercolor style",
"size": "1024*1536"
}' | python3 -c "import sys,json; print(json.load(sys.stdin)['task_id'])")
echo "Task ID: $TASK_ID"
# Step 2: Poll until complete
while true; do
STATUS=$(curl -s "https://api.novita.ai/v3/async/task-result?task_id=$TASK_ID" \
-H "Authorization: Bearer $NOVITA_API_KEY")
STATE=$(echo $STATUS | python3 -c "import sys,json; print(json.load(sys.stdin)['task']['status'])")
echo "Status: $STATE"
if [ "$STATE" = "TASK_STATUS_SUCCEED" ]; then
echo $STATUS | python3 -c "import sys,json; print(json.load(sys.stdin)['images'][0]['image_url'])"
break
elif [ "$STATE" = "TASK_STATUS_FAILED" ]; then
echo "Generation failed"
break
fi
sleep 2
done
Ключевые параметры
| Параметр | Тип | Обязательный | По умолчанию | Примечания |
|---|---|---|---|---|
prompt |
string | Да | — | Текстовое описание изображения для генерации. Поддерживает английский и китайский языки. |
size |
string | Нет | 1024*1024 |
Ширина × высота в пикселях, формат W*H. Каждое измерение: 256–1536. |
Варианты размера, которые стоит рассмотреть:
| Сценарий использования | Рекомендуемый размер |
|---|---|
| Квадрат (соцсети, профиль) | 1024*1024 |
| Портрет (мобайл, плакат) | 1024*1536 |
| Ландшафт (баннер, превью) | 1536*1024 |
На этом эндпоинте нет отдельных параметров negative_prompt, steps или cfg_scale — модель принимает эти решения внутри себя. Сосредоточьте промпт на том, что должно быть на изображении, и на его визуальном стиле.
Что Qwen Image генерирует хорошо
Архитектура 20B MMDiT дает Qwen Image реальное преимущество в нескольких конкретных областях:
Текст на изображениях. Большинство моделей генерации изображений с трудом справляются с читаемым текстом — слова размываются, буквы меняются местами, многострочные макеты рассыпаются. Qwen Image обрабатывает английский и китайский текст с заметно большей точностью. Плакаты, вывески, этикетки и графика с подписями — это рабочие сценарии, а не лотерея.
Семантическая согласованность. Когда промпт описывает сцену с несколькими элементами и конкретными пространственными отношениями, Qwen Image чаще надежно следует задуманной композиции, чем более маленькие или старые архитектуры.
Следование промпту в полном объеме. Длинные детальные промпты, описывающие множество атрибутов — сцену, освещение, стиль, цветовую палитру, конкретные объекты — дают результат, отражающий весь промпт, а не зацикливающийся на одном ключевом слове.
Где она подходит хуже: сценарии генерации в реальном времени или интерактивные сценарии. Асинхронный паттерн означает неизбежную задержку между запросом и результатом. Если вашему сценарию требуется отклик за доли секунды, этот эндпоинт не подходит.
Частые ошибки и их устранение
401 Unauthorized: Проверьте, что заголовок Authorization отформатирован как Bearer <key> с пробелом после Bearer. Убедитесь, что ключ активен в консоли Novita AI.
400 Bad Request для size: В параметре size в качестве разделителя должна использоваться * (например, 1024*1024), а не x, × или JSON-массив. Каждое измерение должно быть от 256 до 1536.
TASK_STATUS_FAILED без причины: Обычно вызвано промптом, который срабатывает на контентную фильтрацию. Упростите промпт и повторите попытку. Избегайте промптов с откровенным насилием, сексуальным контентом или контентом, который может совпасть с фильтрами безопасности.
Срок действия URL изображения истек (403 или 404 при обращении к URL): Поле image_url_ttl показывает, сколько времени URL валиден. Скачайте изображение сразу после успешного опроса или сохраните его в собственном объектном хранилище.
Медленный опрос: Время генерации зависит от нагрузки на сервер. Разумно начинать опрос с интервалом 2 секунды. Если задача все еще в статусе TASK_STATUS_QUEUED через 10 секунд, продолжайте опрос — глубина очереди может резко возрасти в часы пиковой нагрузки.
FAQ
Существует ли OpenAI-совместимый эндпоинт для Qwen Image txt2img?
Нет. Эндпоинт /v3/async/qwen-image-txt2img использует нативный асинхронный API изображений Novita AI, а не формат генерации изображений OpenAI. Если вам нужна OpenAI-совместимая генерация изображений, Novita AI предлагает модели FLUX и SDXL через совместимые эндпоинты — см. документацию Novita AI.
В чем разница между этим эндпоинтом и эндпоинтом Qwen Image Edit?
Этот эндпоинт генерирует изображения только из текстового запроса — входное изображение не требуется. Эндпоинт Qwen Image Edit принимает существующее изображение и текстовую инструкцию и изменяет изображение соответствующим образом. Используйте txt2img, когда создаете с нуля; используйте edit, когда нужно что-то изменить в существующем изображении.
Поддерживает ли модель соотношения сторон, отличные от квадратного?
Да. Используйте параметр size, чтобы задавать ширину и высоту независимо в диапазоне от 256 до 1536 пикселей на каждое измерение. Вертикальные соотношения (например, 1024*1536) хорошо подходят для портретного контента; широкие (например, 1536*1024) — для баннеров и превью.
Как получить одинаковые результаты при нескольких генерациях?
На эндпоинте txt2img нет параметра seed. Каждый запрос дает другой результат. Если вам нужен воспроизводимый результат, сразу сохраните URL изображения и храните изображение в собственном хранилище, а не генерируйте заново.
Можно ли использовать этот API для пакетной обработки?
Да. Отправляйте несколько запросов на генерацию и собирайте ID задач, затем опрашивайте их параллельно. Каждый запрос возвращает собственный task_id, поэтому пакетные сценарии реализуются просто — вам не нужно ждать завершения одного запроса, чтобы отправить следующий.
