Qwen Image Edit 快速入門：以文字指令編輯圖片

Novita AI 上的 Qwen Image Edit API 使用自然語言指令修改現有影像，由 20B Qwen-Image 模型驅動。本快速入門涵蓋完整的非同步工作流程：提交編輯請求（包含來源影像與提示）、接收任務 ID、輪詢直到編輯完成，並取回已編輯影像的 URL。端點為 POST https://api.novita.ai/v3/async/qwen-image-edit。

目錄

何時使用本快速入門

當您需要進行以下操作時，請使用本指南：

• 透過文字指令修改現有影像 — 更換背景、轉換風格、移除元素、旋轉物件或調整衣物，無須從頭重建影像。
• 在保留未修改區域的同時，進行精準編輯。模型的雙路徑架構（Qwen2.5-VL 負責語義理解 + VAE 編碼器負責外觀保留）專門設計用來防止編輯擴散到您未描述的區域。
• 精確編輯影像中的文字。Qwen Image Edit 可處理標誌、海報與品牌素材中的中英文文字替換 — 保留字型、大小以及周圍的視覺風格，這是多數影像生成模型難以做到的。

如果您只使用提示詞（無輸入影像）生成全新影像，請改用 Qwen Image txt2img 快速入門。如需模型功能、基準測試與架構的完整概述，請參閱 Qwen-Image on Novita AI 發布文章。

步驟 1：取得您的 Novita API 金鑰

建立 Novita AI 帳號，並前往 API 金鑰管理。產生一組金鑰，並在執行下列任何程式碼範例前，將其儲存為環境變數：

export NOVITA_API_KEY="your_api_key_here"

請勿將金鑰放在客戶端程式碼、前端套件或版本控制中。若金鑰遭洩露，請從相同設定頁面進行輪換。

步驟 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 文件	Novita AI Qwen Image Edit 參考

此 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：輪詢取得結果

使用 task_id 作為查詢參數，向任務結果端點發送 GET 請求：

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 <key> 格式正確
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"編輯任務失敗：{data}")
        time.sleep(interval)
    raise TimeoutError(f"任務 {task_id} 在 {timeout} 秒內未完成")


if __name__ == "__main__":
    task_id = submit_edit(
        image="https://example.com/product-photo.jpg",
        prompt="將外套改為紅色皮夾克，保留背景",
    )
    print(f"任務 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 "任務 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"
  if [ "$STATUS" = "TASK_STATUS_SUCCEED" ]; then
    echo "$RESULT" | jq -r '.images[].image_url'
    break
  elif [ "$STATUS" = "TASK_STATUS_FAILED" ]; then
    echo "任務失敗："
    echo "$RESULT" | jq .
    exit 1
  fi
  sleep 2
done

若尚未安裝 jq，請使用 apt install jq（Debian/Ubuntu）或 brew install jq（macOS）進行安裝。

關鍵參數

參數	類型	必要	預設值	說明
prompt	字串	是	—	描述所需編輯的自然語言指令
image	字串	是	—	來源影像，可為 URL 或 base64 編碼字串
seed	整數	否	隨機	固定隨機種子，用於跨多次執行產出可重現結果
output_format	字串	否	jpeg	輸出格式 — 請參考 API 文件以了解可接受的值

撰寫有效提示的技巧：具體性至關重要。「將看板上的文字改為『夏季特賣』」能給予模型明確且有限的任務。「改善圖片」則不行。當您只想更改某個元素並保留其餘部分時，請明確指出要保留的內容：「將夾克顏色改為紅色，保持背景與臉部不變」。這有助於 VAE 編碼器路徑鎖定未觸及的區域。

使用 seed 進行疊代：調整提示時，固定種子可讓您直接比較編輯結果 — 輸出變化來自提示的改動，而非隨機取樣。一旦找到有效的提示，若希望跨多次編輯產出多樣性，則可移除種子限制。

典型使用場景

背景替換：「將背景替換為簡約白色攝影棚」 — Qwen Image Edit 在更換環境的同時，保留主體的邊緣與光影。當主體相對於原始背景有清晰邊界時，效果可靠。

影像中的文字：替換商店招牌、海報標題或產品標籤上的文字 — 包含中文與英文。模型能比生成式內補（inpainting）方法更好地保留字型樣式與周圍視覺上下文，後者往往會重新生成整個區域。

風格轉換：「轉換為油畫風格」或「使其看起來像鉛筆素描」套用於來源影像，而非從頭描述。VAE 編碼器路徑會保留原始構圖與物體位置，而提示則驅動風格轉換。

物件級別變更：更換衣物、改變特定物品的顏色、添加或移除配件。指令應明確指出要變更的具體元素，以防止編輯影響相鄰區域。

IP 轉換與物件旋轉：模型支援視角合成變化（例如旋轉物件以顯示不同角度），以及轉換角色或產品影像的視覺風格 — 這些使用案例在 Qwen-Image-Edit on Novita AI 概述 中有詳細說明。

疑難排解

輸出看起來沒有變化：指令可能過於模糊。請更明確指定要針對的元素：「將車子的顏色從藍色改為紅色」，而非「讓它變紅」。

非預期的編輯擴散到不應影響的區域：對於高度特定的局部編輯，請在提示中加入明確的保留描述：「只更改 X，保持 Y 不變」。過於開放的提示會讓模型有自由度重新詮釋整個構圖。

任務完成但影像 URL 回傳 403 或 404：image_url_ttl 欄位（以秒為單位）告訴您 URL 的有效期限。若您在 TTL 之後才輪詢該 URL，該 URL 已過期。請在成功輪詢後立即下載影像。

401 未授權：確認 Authorization 標頭格式為 Bearer <key>，且 Bearer 後有空白。請在 Novita AI 主控台 確認金鑰有效且未被撤銷。

任務持續逾時：影像編輯比文字生成耗時更長 — 正常負載下通常為 15–60 秒。如果任務經常超過您的逾時設定，請在將其視為失敗前加大輪詢時間視窗。

常見問題

來源影像會留在 Novita 的伺服器上嗎？

您的影像會透過 HTTPS 上傳至 Novita AI 的 API 並在其基礎設施上處理。在傳送包含敏感個人資訊、私密健康資料或機密內容的影像前，請先審閱 Novita AI 的資料處理政策。

可以使用 base64 編碼的影像而非 URL 嗎？

可以。在 image 欄位中傳入原始 base64 字串。請查閱 API 參考 以了解 base64 酬載的大小限制。

是否有用於一致性的 seed 參數？

有 — 可選的 seed 參數可固定隨機狀態，使相同提示與影像產出一致的結果。這在疊代提示詞時很有用，可避免因重新取樣而產生的輸出雜訊。

能否將此端點用於批次作業？

可以。同時提交多個編輯請求並收集 task_id 值，然後並行輪詢它們。每個請求都是獨立的。

此端點與 Qwen Image txt2img 端點有何不同？

編輯端點需要來源影像，並產出經過修改的版本。txt2img 端點 則完全根據文字提示生成影像 — 不需要輸入影像。當您有現有內容要修改時使用編輯端點；當您從頭建立時使用 txt2img。

推薦文章

• Qwen Image 文字轉圖片快速入門：從提示詞生成影像
• Qwen-Image-Edit on Novita AI：專業級編輯，每張僅需 $0.02
• Novita AI 現提供 Qwen-Image：先進的 20B 文字轉圖片模型