Qwen Image 3.0 API：料金・導入・実装ガイド

Qwen Image 3.0 は、テキストからの画像生成と参照画像の編集を一つの非同期 API で提供します。APIMart では、タスクを送信してステータスをポーリングし、完了後に一枚以上の生成画像を取得します。

本ガイドでは、導入前に確認すべき Standard／Pro の最新料金、認証、リクエストパラメータ、レスポンス解析、ポーリング、再試行、出力保存をまとめます。モデルの機能やベンチマークについては、Qwen Image 3.0 リリースガイドも参照してください。

Qwen Image 3.0 の料金とアクセス

APIMart では、次の二つのモデル ID を利用できます。

• qwen-image-3.0：Standard
• qwen-image-3.0-pro：Pro

料金は入力 Token 数ではなく、生成画像数に基づきます。下表は 2026 年 8 月 27 日時点の APIMart 料金ページの表示内容であり、今後変更される可能性があります。

Standard と Pro の料金比較

Standard は現在、1K と 2K が同額です。Pro の 2K は 1K の二倍です。Qwen Image 3.0 API ドキュメントによると、生成失敗時は料金が返金され、参照画像には別途生成料金がかかりません。

実際のワークロードを見積もる

基本式は次のとおりです。

月額コスト = 完成した画像数 × 画像一枚あたりの料金

n は出力数を指定するため、n: 4 のリクエストでは四枚分の料金が発生し得ます。プロンプトの試行、バリエーション、再生成も予算に含めてください。

通常の下書きや素材には Standard が適しています。文字描画、構図、細部の改善が追加費用に見合う場合に Pro を検討します。Pro を使う場合は、反復作業を 1K で行い、承認済みの高解像度成果物に 2K を使うと管理しやすくなります。

アクセスと認証

APIMart のアカウントを作成し、十分な残高を追加して、コンソールで API キーを発行します。キーはサーバー側の Secret または環境変数に保存し、ブラウザーコードや NEXT_PUBLIC_* 変数には絶対に公開しないでください。

Base URL と Bearer Token

本ガイドの Base URL は次のとおりです。

https://api.apimart.ai/v1

API キーを Bearer Token として送信します。

Authorization: Bearer <your_api_key>
Content-Type: application/json

キーがない、または無効な場合は通常 401、残高不足では 402、レート制限では 429 が返ります。サーバーでレスポンス本文とリクエスト情報を記録する際は、API キーを必ず伏せてください。

画像生成・編集と非同期ワークフロー

生成と編集はいずれも POST /v1/images/generations を使います。画像の完成を待たず、最初にタスク ID が返ります。

主なリクエストパラメータ

カスタム寸法では各辺を 512～2,048 ピクセル、アスペクト比を 1:8～8:1 に収めます。参照画像は JPEG、PNG、BMP、TIFF、WebP、GIF に対応し、文書上の上限は一枚 10 MB です。制限は変更される可能性があるため、公開前に生成 API リファレンスを確認してください。

Qwen Image 3.0 公式発表では、12 言語のネイティブ文字描画に対応すると説明されています。文字中心の画像では、正確に表示したい文言を引用符で囲み、対象解像度でスペル、フォント、配置を検証しましょう。

テキストから画像を生成する例

{
  "model": "qwen-image-3.0",
  "prompt": "『サマーセール』という文字を正確に表示する商品バナー、太い幾何学フォント、暖かいオレンジ色の背景",
  "resolution": "1K",
  "size": "16:9",
  "n": 1,
  "prompt_extend": true
}

参照画像を編集する例

既存画像を変換または再構成する場合は image_urls を追加します。

{
  "model": "qwen-image-3.0-pro",
  "prompt": "商品の形状は一切変えず、背景を柔らかく照明されたスタジオに置き換える",
  "image_urls": [
    "https://example.com/reference-product.png"
  ],
  "resolution": "2K",
  "n": 1
}

参照 URL は API からアクセスできる必要があります。非公開ファイルには、送信と処理を終えるまで有効な署名付き URL を使うか、用途に応じて対応する Data URL を利用します。

非同期タスクの流れ

処理は次の三段階です。

1. POST /v1/images/generations で生成タスクを送信する。
2. レスポンスの data[0].task_id を取得する。
3. 完了または失敗するまで GET /v1/tasks/{task_id} をポーリングする。

送信時のレスポンス

正常なレスポンスは次の形式です。

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_example"
    }
  ]
}

task_id はトップレベルではなく、data の最初の要素にあります。

ポーリングと完了結果

状態リクエストを連続送信せず、3～5 秒間隔でポーリングしてください。完了したファイルは data.result.images に含まれます。

{
  "code": 200,
  "data": {
    "status": "completed",
    "result": {
      "images": [
        {
          "url": [
            "https://example-cdn.com/generated-image.png"
          ]
        }
      ]
    }
  }
}

APIMart の現行ドキュメントでは、完成画像はプラットフォーム CDN にミラーされ、長期的に利用できるとされています。ただし、保持期間、削除、アクセス制御、配信性能を自社で管理する必要がある場合は、承認済み素材を自社ストレージへコピーしてください。

実装例

Python での実装

次のサーバー側の例は、タスクを送信し、三秒ごとにポーリングして、三分で待機を終了します。

import os
import time
import requests

API_KEY = os.environ["QWEN_API_KEY"]
BASE_URL = "https://api.apimart.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

def generate_image(prompt: str) -> str:
    response = requests.post(
        f"{BASE_URL}/images/generations",
        headers=HEADERS,
        json={"model": "qwen-image-3.0", "prompt": prompt, "resolution": "1K", "n": 1, "prompt_extend": True},
        timeout=30,
    )
    response.raise_for_status()
    task_id = response.json()["data"][0]["task_id"]
    deadline = time.monotonic() + 180

    while time.monotonic() < deadline:
        poll = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        poll.raise_for_status()
        task = poll.json()["data"]
        if task["status"] == "completed":
            return task["result"]["images"][0]["url"][0]
        if task["status"] == "failed":
            raise RuntimeError(task.get("fail_reason", "Generation failed"))
        time.sleep(3)

    raise TimeoutError(f"Task {task_id} did not finish within 180 seconds")

実際のアプリケーションでは、ポーリング前にタスク ID を永続化します。Worker が再起動しても、別の Worker が保存済みタスクを再開でき、重複した生成料金を防げます。

JavaScript での実装

次のコードは信頼できるサーバー環境でのみ実行してください。

const apiKey = process.env.QWEN_API_KEY;
const baseUrl = "https://api.apimart.ai/v1";
const headers = { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" };

async function requestJson(url, options = {}) {
  const response = await fetch(url, { ...options, headers });
  const payload = await response.json();
  if (!response.ok) throw new Error(`APIMart ${response.status}: ${JSON.stringify(payload)}`);
  return payload;
}

async function generateImage(prompt) {
  const submission = await requestJson(`${baseUrl}/images/generations`, {
    method: "POST",
    body: JSON.stringify({
      model: "qwen-image-3.0", prompt, resolution: "1K", n: 1, prompt_extend: true,
    }),
  });
  const taskId = submission.data[0].task_id;
  const deadline = Date.now() + 180_000;

  while (Date.now() < deadline) {
    await new Promise((resolve) => setTimeout(resolve, 3000));
    const { data: task } = await requestJson(`${baseUrl}/tasks/${taskId}`);
    if (task.status === "completed") return task.result.images[0].url[0];
    if (task.status === "failed") throw new Error(task.fail_reason ?? "Generation failed");
  }
  throw new Error(`Task ${taskId} did not finish within 180 seconds`);
}

cURL でも同じ送信・ポーリング手順を確認できます。

curl -X POST https://api.apimart.ai/v1/images/generations \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen-image-3.0","prompt":"ミニマルな商品写真","resolution":"1K","n":1}'

curl https://api.apimart.ai/v1/tasks/<task_id> \
  -H "Authorization: Bearer <your_api_key>"

プロダクション導入チェックリスト

一度 API が成功しただけでは十分ではありません。信頼できる画像パイプラインには、回数を制限した再試行、永続的なタスク状態、可観測性、管理可能なストレージが必要です。

エラーと再試行方針

結果が不明なネットワークタイムアウトの直後に、生成をむやみに再送信しないでください。最初の要求が受理済みなら、二回目の送信で重複タスクと追加料金が発生します。返されたタスク ID を保存し、送信の再試行とポーリングの再試行を分離しましょう。

公開前の確認事項

• API キーをサーバー側の Secret にのみ保存する。
• 送信前に prompt、resolution、size、n、参照画像を検証する。
• タスク ID と現在の状態を永続化する。
• 3～5 秒ごとにポーリングし、アプリケーション側のタイムアウトを設ける。
• 429 と再試行可能な 5xx にジッター付き指数バックオフを使う。
• 実測したレート制限と遅延に合わせて同時実行数を制限する。
• 完了、失敗、タイムアウト、重複を別々に計測する。
• 保持を明確に管理する必要があれば、承認済み出力を自社ストレージにコピーする。
• リリース前に Qwen Image 3.0 モデルページ、料金ページ、API ドキュメントを再確認する。

Qwen Image 3.0 で画像を生成

APIMart の統合 API で Standard と Pro を試し、1K と 2K の出力を比較して、画像ワークフローを試作からプロダクションへ移行できます。

Qwen Image 3.0 を試す

よくある質問

ポーリングは何分でタイムアウトすべきですか？

APIMart は 3～5 秒間隔のポーリングと、約三分のクライアントタイムアウトを推奨しています。これは初期値として使い、実際の遅延に合わせて調整してください。タスク ID を保存しておけば、タイムアウトしたタスクも後から照合できます。

結果 URL は 24 時間で期限切れになりますか？

現行の APIMart 生成 API 文書では、出力はプラットフォーム CDN にミラーされ、長期利用できるとされています。そのため、以前の「24 時間で失効」という説明はこの連携には当てはまりません。重要な素材は、期限が明示されていない外部保存だけに依存せず、自社管理のストレージに保存してください。

Base64 の参照画像を送信できますか？

はい。現在の API 文書では、image_urls に 1～3 個の公開 HTTP/HTTPS URL または対応する Base64 Data URL を指定できます。各画像は対応形式と 10 MB の上限を満たす必要があります。

1K と 2K はどう使い分けますか？

高速な反復や細部を最優先しない素材には 1K、細かな文字、鮮明な輪郭、大判表示が必要な最終画像には 2K を選びます。Standard は現在同額ですが、Pro の 2K は 1K より高いため、遅延、画質、コストを合わせて評価してください。