Novita AIのQwen Image テキスト読み込みAPIは、20B Qwen Imageモデルを使用してテキストプロンプトから画像を生成します。このモデルは、正確な編集タスクを実行するQwen Image Edit APIと同じ基盤です。このクイックスタートでは、生成リクエストの送信、タスクIDの取得、完了までのポーリング、画像URLの取得という、完全な非同期ワークフローを解説します。エンドポイントは POST https://api.novita.ai/v3/async/qwen-image-txt2img です。
このクイックスタートを活用する場面
以下のようなケースでこのガイドを活用してください。
POST /v3/async/qwen-image-txt2imgを使用して、英語または中国語で高品質なテキストレンダリングを備えた画像をテキストプロンプトから生成する。- 画像内のテキストの可読性が重要なポスター、グラフィックアセット、イラストコンテンツを作成するパイプラインを構築する。
- ローカルのGPUインフラで20Bモデルを実行する代わりに、ホステッドAPIに対して迅速にプロトタイピングを行う。
Qwen Imageモデルは特に、出力画像に可読性の高いスタイル付きテキストを埋め込むことに優れています。ポスター、看板、プロダクトモックアップ、カバーグラフィックなどがその例です。ユースケースがゼロからの生成ではなく既存画像の編集である場合は、代わりにQwen Image Edit 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) |
| 公式ドキュメン | Nova AI Qwen Image t2img 参照 |
APIは、すべてのNovita AI画像生成エンドポイントに共通する2ステップの非同期パターンに従います。生成呼び出しは task_id のみを返します。結果エンドポイントを個別にポーリングしてタスクが完了するのを待ちます。
価格は1画像あたり$0.02で、Qwen Image Editエンドポイントと同じです。コスト見積もりを作成する前に、Nova 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 の値（秒単位）で有効期間がわかります。すぐに画像をダウンロードするか、長期保存が必要な場合は独自のストレージを介してプロキシしてください。
処理すべきステータス値：
| ステータス | 意味 |
|---|---|
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による例
完全なワークフローの2コマンドパターン：
# 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。 |
検討すべきサイズオプション：
| ユースケース | 推奨サイズ |
|---|---|
| 正方形（SNS、プロフィール） | 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 on size：size パラメータは区切り文字として * を使用する必要があります（例：1024*1024）。x、×、JSON配列は使用できません。各辺は256から1536の間である必要があります。
TASK_STATUS_FAILED（理由なし）：通常はコンテンツフィルタリングをトリガーするプロンプトが原因です。プロンプトを簡略化して再試行してください。明示的な暴力、性的コンテンツ、またはセーフティフィルターに一致する可能性のあるコンテンツを含むプロンプトは避けてください。
Image URL expired（URLで403または404）：image_url_ttl フィールドでURLの有効期間がわかります。ポーリングが成功したらすぐに画像をダウンロードするか、独自のオブジェクトストレージに保存してください。
ポーリングが遅い：生成時間はサーバーの負荷によって異なります。2秒間隔でポーリングを開始するのが妥当です。10秒経ってもタスクが TASK_STATUS_QUEUED のままの場合は、ピーク時の使用状況によってキュー深度が急上昇する可能性があるため、ポーリングを続けてください。
FAQ
Qwen Image txt2imgに対応したOpenAI互換のエンドポイントはありますか？
いいえ。/v3/async/qwen-image-txt2img エンドポイントは、OpenAIの画像生成形式ではなく、Novita AI独自の非同期画像APIを使用しています。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 を返すため、バッチワークフローは簡単です。1つが完了するのを待ってから次のリクエストを送信する必要はありません。
