Novita AI 上的 Qwen Image 文生图 API 使用 200 亿参数的 Qwen Image 模型根据文本提示词生成图像——该模型与驱动 Qwen Image Edit API 进行精确编辑任务的模型基于相同的架构。本快速入门涵盖完整的异步工作流：提交生成请求、获取任务 ID、轮询完成状态以及获取图像地址。端点为 POST https://api.novita.ai/v3/async/qwen-image-txt2img。
何时使用本快速入门
在以下场景中，你可以参考本指南：
- 通过
POST /v3/async/qwen-image-txt2img从文本提示词生成图像，并支持英文或中文的高质量文本渲染。 - 构建能够创建海报、图形素材或插画内容的工作流，且图像中的文字清晰可读。
- 快速针对托管 API 进行原型开发，无需在本地 GPU 基础设施上运行 200 亿参数模型。
Qwen Image 模型特别擅长生成包含可读、带样式文本的图像——例如海报、标识、产品效果图和封面图形。如果你的用例涉及编辑现有图像而非从头生成，请改用 Qwen Image Edit API。如果你想全面了解 Qwen Image 模型的能力和基准测试结果，Novita AI 的 Qwen Image 发布文章 详细介绍了架构和基准测试结果。
第一步：获取你的 Novita API 密钥
创建一个 Novita AI 账户，然后进入 API 密钥管理 页面。生成一个密钥并将其保存为环境变量：
export NOVITA_API_KEY="your_api_key_here"
请勿将密钥放入客户端代码、前端打包文件或版本控制系统中。
第二步：确认端点和模型
| 项 | 值 |
|---|---|
| 生成端点 | POST https://api.novita.ai/v3/async/qwen-image-txt2img |
| 结果轮询端点 | GET https://api.novita.ai/v3/async/task-result?task_id=<id> |
| 模型 | Qwen Image（200 亿参数 MMDiT） |
| API 文档 | Novita AI Qwen Image txt2img 参考 |
该 API 遵循所有 Novita AI 图像生成端点通用的两步异步模式。生成调用仅返回一个 task_id；你需要单独轮询结果端点，直到任务完成。
价格为每张图像 0.02 美元，与 Qwen Image Edit 端点一致。在制定成本估算之前，请访问 Novita AI 定价页面 确认当前费率。
第三步：发送你的第一个请求
向生成端点发送 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。你将在下一步中使用它。
第四步：轮询获取结果
使用 task_id 作为查询参数，对任务结果端点发起 GET 请求：
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 是一个有时效性的地址——image_url_ttl 的值（以秒为单位）告诉你该地址的有效期。请及时下载图像，或如果你需要长期访问，则通过自己的存储代理。
需要处理的状态值：
| 状态 | 含义 |
|---|---|
TASK_STATUS_QUEUED |
请求已入队，尚未开始 |
TASK_STATUS_PROCESSING |
生成进行中 |
TASK_STATUS_SUCCEED |
图像已就绪；读取 images[0].image_url |
TASK_STATUS_FAILED |
生成失败；检查 task.reason |
Python 示例：端到端流程
以下脚本提交生成请求，轮询直到完成，并打印图像地址。
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 |
字符串 | 是 | — | 要生成图像的文本描述。支持英文和中文。 |
size |
字符串 | 否 | 1024*1024 |
以像素为单位的宽度 × 高度，格式为 W*H。各维度范围：256–1536。 |
可考虑使用的尺寸选项：
| 使用场景 | 推荐尺寸 |
|---|---|
| 方形（社交媒体、头像） | 1024*1024 |
| 竖版（移动端、海报） | 1024*1536 |
| 横版（横幅、缩略图） | 1536*1024 |
该端点没有单独的 negative_prompt、steps 或 cfg_scale 参数——模型内部自行处理这些决策。请将提示词集中在图像应包含的内容及其视觉风格上。
Qwen Image 擅长生成的内容
200 亿参数的 MMDiT 架构使 Qwen Image 在以下几个特定方面具有明显优势：
图像中的文字。 大多数图像生成模型在生成可读文本方面表现不佳——文字模糊、字母混淆、多行布局崩溃。Qwen Image 在处理英文和中文文本时准确性显著更高。海报、标识、标签和带说明文字的图形成为可行的用例，而非碰运气。
语义一致性。 当提示词描述包含多个元素和特定空间关系的场景时，Qwen Image 往往能比更小或更旧的架构更可靠地体现布局意图。
大规模提示词遵循能力。 描述多种属性的长而详细的提示词——场景、光照、风格、调色板、特定物体——能够生成反映完整提示词的输出，而非仅抓住一个关键词。
不适合的场景：实时或交互式的生成工作流。异步模式意味着请求与结果之间存在固有的延迟。如果你的用例需要亚秒级反馈，此端点并不合适。
常见错误及解决方法
401 未授权：检查 Authorization 头的格式是否为 Bearer <key>，在 Bearer 后有一个空格。确认密钥在 Novita AI 控制台 中处于激活状态。
400 错误请求（size 参数）：size 参数必须使用 * 作为分隔符（例如 1024*1024），而不是 x、× 或 JSON 数组。每个维度必须在 256 到 1536 之间。
TASK_STATUS_FAILED 且无原因：通常由触发内容过滤的提示词导致。简化提示词后重试。避免包含明显暴力、色情内容或可能匹配安全过滤器的提示词。
图像地址已过期（访问地址返回 403 或 404）：image_url_ttl 字段告诉你地址的有效期。轮询成功后立即下载图像，或将其存储到自己的对象存储中。
轮询缓慢：生成时间随服务器负载变化。以 2 秒间隔开始轮询是合理的。如果任务在 10 秒后仍处于 TASK_STATUS_QUEUED 状态，请继续轮询——队列深度在高峰使用期间可能激增。
常见问题
Qwen Image txt2img 是否有兼容 OpenAI 的端点？
没有。/v3/async/qwen-image-txt2img 端点使用的是 Novita AI 的原生异步图像 API，而非 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 参数。每次请求都会产生不同的结果。如果需要可复现的输出，请立即保存图像地址，并将图像存储到自己的存储中，而不是重新生成。
能否在批处理任务中使用此 API？
可以。提交多个生成请求并收集任务 ID，然后并行轮询它们。每个请求返回自己的 task_id，因此批处理工作流非常简单——无需等待一个完成后再提交下一个。
