Novita AI 上的 Qwen Image 文字轉圖片 API 使用 20B 參數的 Qwen Image 模型，從文字提示詞生成圖片——這與 Qwen Image 編輯 API 採用相同的基礎模型，以實現精確的編輯任務。本快速入門涵蓋完整的非同步工作流程：提交生成請求、取得任務 ID、輪詢直到完成，以及取得圖片 URL。端點為 POST https://api.novita.ai/v3/async/qwen-image-txt2img。
何時使用本快速入門
當您需要以下功能時，請參考本指南：
- 使用
POST /v3/async/qwen-image-txt2img從文字提示詞生成圖片，支援英文或中文的高品質文字渲染。 - 建立需要圖像內文字可讀性的海報、圖形素材或插圖內容的處理流程。
- 快速針對託管 API 進行原型開發，而非在本地 GPU 基礎設施上執行 20B 模型。
Qwen Image 模型在生成內嵌可讀、有風格文字的圖片方面表現尤為出色——例如海報、標誌、產品模型和封面圖形。如果您的使用案例是編輯現有圖片而非從頭生成，請參閱 Qwen Image 編輯 API。如果您想全面了解 Qwen Image 模型的能力與基準測試結果，Novita AI 的 Qwen Image 發佈文章 詳細介紹了架構與基準測試結果。
步驟 1：取得您的 Novita API 金鑰
建立一個 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 編輯端點一致。在建立成本估算前，請先至 Novita AI 定價頁面 確認當前費率。
步驟 3：發送您的第一個請求
使用 prompt 和可選的 size 參數向生成端點發送 POST 請求：
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：輪詢以取得結果
使用 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 是一個有時效性的 URL——image_url_ttl 值（以秒為單位）告訴您該 URL 的有效期限。請立即下載圖片，或如果您需要長期存取，請透過您自己的儲存空間進行代理。
需要處理的狀態值：
| 狀態 | 意義 |
|---|---|
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 過期（URL 返回 403 或 404）：image_url_ttl 欄位告訴您 URL 的有效期限。請在輪詢成功後立即下載圖片，或將其儲存在您自己的物件儲存中。
輪詢速度慢：生成時間因伺服器負載而異。以 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 編輯端點有何不同？
此端點僅根據文字提示詞生成圖片——無需輸入圖片。Qwen Image 編輯端點 則接受一張現有圖片加上文字指令，並據此修改圖片。當您從頭創作時使用 txt2img；當您需要修改現有圖片中的某些內容時使用編輯功能。
模型是否支援非正方形的寬高比？
是的。使用 size 參數獨立設定寬度和高度，每個維度範圍從 256 到 1536 像素。較高的比例（例如 1024*1536）適合直向內容；較寬的比例（例如 1536*1024）適合橫幅和縮圖。
如何在不同生成之間獲得一致的結果？
txt2img 端點沒有 seed 參數。每個請求都會產生不同的結果。如果您需要可重現的輸出，請立即儲存圖片 URL 並將圖片存放到您自己的儲存空間，而非重新生成。
我可以在批次作業中使用此 API 嗎？
可以。提交多個生成請求並收集任務 ID，然後並行輪詢它們。每個請求都會返回自己的 task_id，因此批次工作流程非常簡單——您無需等待一個完成後再提交下一個。
