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 クイックスタート を使用してください。モデルの機能、ベンチマーク、アーキテクチャの完全な概要については、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-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 になるまで結果エンドポイントをポーリングします。これは、txt2img エンドポイントを含むすべての Novita AI 画像生成エンドポイントで使用される同じ 2 ステップパターンです。
料金は画像 1 枚あたり $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": "Change the background to a snowy mountain landscape",
"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 |
生成に失敗しました。エラーフィールドで理由を確認してください。 |
ステップ 5：料金、制限、および一般的なエラーを確認する
料金：画像 1 枚あたり $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"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="Change the jacket to a red leather jacket, preserve the background",
)
print(f"Task ID: {task_id}")
result = poll_result(task_id)
for img in result["images"]:
print(img["image_url"])
cURL の例
JSON 解析に jq を使用した 2 コマンドワークフロー：
#!/bin/bash
# Step 1: submit the edit request
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": "Convert to watercolor painting style, preserve the subject and composition",
"image": "https://example.com/landscape.jpg"
}' | jq -r '.task_id')
echo "Task ID: $TASK_ID"
# Step 2: poll until complete
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 | いいえ | ランダム | 複数の実行で再現可能な出力のための固定シード |
output_format |
string | いいえ | jpeg |
出力形式 — 受け入れ可能な値については API ドキュメントを参照 |
効果的なプロンプトの書き方：具体性が重要です。「看板のテキストを「Summer Sale」に変更して」は、モデルに明確で範囲が限定されたタスクを与えます。「画像を改善して」はそうではありません。1 つの要素を変更し、他のすべてをそのままにしたい場合は、保持したいものを指定してください。「ジャケットの色を赤に変更して、背景と顔はそのままにして」これにより、VAE エンコーダパスが手を加えない領域をロックする役割を果たせるようになります。
反復のための seed の使用：プロンプトを調整する際に、シードを固定することで編集内容を直接比較できます。出力のばらつきは、ランダムサンプリングではなくプロンプトの変更によるものになります。適切なプロンプトが見つかったら、複数の編集間で出力の多様性が必要な場合はシード制約を削除してください。
典型的なユースケース
背景の置き換え：「背景をミニマリストな白いスタジオに置き換えて」 — Qwen Image Edit は、環境を交換しながら被写体のエッジと照明を保持します。被写体が元の背景に対して明確な境界を持っている場合に確実に機能します。
画像内のテキスト：店舗の看板、ポスターヘッドライン、製品ラベルの新しいテキストへの置き換え（中国語と英語を含む）。このモデルは、領域全体を再生成する傾向がある生成インペインティングアプローチよりも、フォントスタイルと周囲のビジュアルコンテキストを保持します。
スタイル変換：「油絵スタイルに変換して」や「これを鉛筆画のように見せて」をゼロから記述するのではなく、ソース画像に適用します。VAE エンコーダパスは元の構図とオブジェクトの配置を保持し、プロンプトがスタイル変換を推進します。
オブジェクトレベルの変更：衣類の交換、特定のアイテムの色の変更、アクセサリーの追加または削除。指示では、編集が隣接領域に影響を与えないように、変更する特定の要素を指定する必要があります。
IP 変換とオブジェクトの回転：このモデルは、ビュー合成の変更（オブジェクトを回転させて別の角度を表示するなど）と、キャラクターや製品イメージのビジュアルスタイル間の変換をサポートします。これらのユースケースは Novita AI 上の Qwen-Image-Edit 概要 で文書化されています。
トラブルシューティング
出力が変更されていないように見える：指示が十分に具体的ではない可能性があります。対象とする要素をより明示的に指定してください。「車の色を青から赤に変更して」のように、「赤くして」ではなく。
不要な編集が意図しない領域に広がる：非常に特定のローカル編集の場合、プロンプトに明示的な保存文言を含めてください。「X だけを変更し、Y はそのままにして」のように。漠然としたプロンプトは、モデルに構成全体を再解釈する余地を与えます。
タスクは完了するが、画像 URL が 403 または 404 を返す：image_url_ttl フィールド（秒単位）は、URL が有効な期間を示します。TTL より後に URL をポーリングすると、URL は期限切れになっています。ポーリングが成功したらすぐに画像をダウンロードしてください。
401 Unauthorized：Authorization ヘッダーの形式が正確に Bearer <key>（Bearer の後にスペース）であることを確認してください。キーがアクティブであり、Novita AI コンソール で失効していないことを確認してください。
タスクが一貫してタイムアウトする：画像編集はテキスト生成よりも時間がかかります（通常の負荷で通常 15〜60 秒）。タスクがタイムアウトを定期的に超える場合は、障害として処理する前にポーリングウィンドウを拡大してください。
FAQ
ソース画像は Novita のサーバーに残りますか？
お客様の画像は HTTPS 経由で Novita AI の API にアップロードされ、そのインフラストラクチャ上で処理されます。機密性の高い個人情報、プライベートな健康データ、または機密コンテンツを含む画像を送信する前に、Novita AI のデータ処理ポリシーを確認してください。
URL の代わりに base64 エンコードされた画像を使用できますか？
はい。image フィールドに raw base64 文字列を渡してください。base64 ペイロードのサイズ制限については API リファレンス を参照してください。
一貫性のための seed パラメーターはありますか？
はい。オプションの seed パラメーターはランダム状態を固定するため、同じプロンプトと画像で一貫した結果が得られます。再サンプリングによる出力ノイズなしでプロンプトの文言を反復するのに役立ちます。
このエンドポイントをバッチジョブに使用できますか？
はい。複数の編集リクエストを並行して送信し、task_id 値を収集してから、それらを同時にポーリングしてください。各リクエストは独立しています。
Qwen Image txt2img エンドポイントとの違いは何ですか？
編集エンドポイントはソース画像を必要とし、その修正バージョンを生成します。txt2img エンドポイント は、テキストプロンプトのみから画像を生成します（入力画像は不要です）。修正したい既存のコンテンツがある場合は編集エンドポイントを、ゼロから作成する場合は txt2img を使用してください。
