本文へスキップ
PershotSTUDIO
ログイン
ウェイトリスト

Qwen-ImageAPIリファレンス

Qwen-Imageモデルを使って、コードから画像の生成と編集を行えます：3ステップのクイックスタート、すべてのフィールド、画像ごとのクレジット、Webhookとべき等性。

ベータエンドポイントPOST /v1/images/generationsOpenAPIllms.txt
API の利用を申請

開発者APIは申請制です。

画像APIはベータ版のため、フィールドは変更される場合があります。スタジオには影響しません。

クイックスタートは3回の呼び出しで

キーを設定し、価格上限を付けてジョブを送信し、結果を読み取ります。

  1. 01

    キーを設定する

    開発者APIは申請制です。スタジオの「APIキー」から申請してください。キーは1回だけ表示されるため、環境変数に保存してください。

    Shell
    export API_KEY="sk_test_…"
  2. 02

    ジョブを送信する

    Idempotency-Keyとmax_creditsの上限を付けて画像をPOSTします。編集モデルはimage_urlも受け取ります。202と待機中のジョブが返り、クレジットが保留されます。

    POST /images/generations
    curl https://api.pershot.app/v1/images/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2512",
    "prompt": "A ceramic mug on a walnut table, soft window light, product photo",
    "size": "1K",
    "aspect_ratio": "1:1",
    "max_credits": 2
  }'
    表示されるはずの内容
    {
  "id": "job_01J9ZK4T8W",
  "object": "job",
  "kind": "image",
  "status": "queued",
  "money_status": "reserved",
  "queue_position": 2,
  "requested_model": "qwen-image-2512",
  "credits_quoted": 2,
  "credits_charged": null
}
  3. 03

    結果を読み取る

    statusがsucceededになるまでジョブをGETします。outputs[].urlは署名付きで24時間後に期限切れになるため、残したいものはダウンロードしてください。

    GET /jobs/{id}
    curl https://api.pershot.app/v1/jobs/job_01J9ZK4T8W \
  -H "Authorization: Bearer $API_KEY"

パラメーターと制限

APIが検証に使うのと同じスキーマから生成されたOpenAPIドキュメントから読み込んでいます。不明なフィールドは拒否されます。

Qwen-Imageのリクエストフィールド
フィールド型許可される値備考
model必須stringqwen-image-2512-lightning · qwen-image-2512 · qwen-image-edit-2511-lightning · qwen-image-edit-2511モデルID。
prompt必須string2–2,000文字生成する内容：被写体、カメラ、光。
sizeデフォルト："1K"string1K · 2K試作と開始フレームには1K、細部の表現には2K。
aspect_ratioデフォルト："1:1"string16:9 · 9:16 · 1:1フレームの形状。
image_url任意stringhttpsのURL動画の開始フレーム。編集モデルでは元画像。公開されているhttpsのURL、またはアップロードURL。
seed任意integer0–2,147,483,647同じ入力で結果を再現します。
quote_id任意stringqt_…POST /v1/quotesの見積もりで実行します。見積もりの有効期間は10分です。
max_credits任意number> 0このジョブの費用の上限。上限を超える場合、ジョブは拒否され、課金されることはありません。
webhook_url任意stringhttpsのURLジョブのイベントを受信するhttpsのURL。
end_user_id任意string1–128文字承認済みの開発者アカウント向け（申請制）：このリクエストに付けるご自身のユーザーID。使用状況に表示されます。
project_id任意stringprj_…
shot_id任意stringsht_…
routing_preference任意stringstability · speed

quote_idとmax_creditsのどちらか一方だけを送信してください。このエンドポイントはmodel "auto"を受け付けません。動画の場合は、先にPOST /v1/auto/planを呼び出し、選ばれたモデルをmax_creditsとともに送信してください。

モデル
qwen-image-2512-lightning生成 · Qwen-Image-2512 · Lightning 4-stepqwen-image-edit-2511-lightning編集 · Qwen-Image-Edit-2511 · Lightningqwen-image-2512生成 · Qwen-Image-2512qwen-image-edit-2511編集 · Qwen-Image-Edit-2511
レートと同時実行数
キーごとに毎分60リクエスト、同時実行はデフォルトでアカウントごとに3ジョブです。キーを増やしても同時実行数は増えません。
AIエージェント向け
AIエージェント向けのテキスト：入力、指定できる値、設定ごとの価格、リクエスト例qwen-image-2512-lightningqwen-image-2512qwen-image-edit-2511-lightningqwen-image-edit-2511

制限

APIが照合するのと同じ表から読み込んでいます。各行に、その制限を誰が確認するのか、超えた場合にどうなるのかを記載しています。

  • 当社が確認当社が確認し、見積もりや保留の前に400を返します。
  • 提供元が確認仕入れ先が確認します。拒否されたジョブは失敗となり、課金されません。
  • 推奨誰も確認しません。範囲内に収めると、より良い結果が得られます。
qwen-image-2512-lightning, qwen-image-2512の制限
制限値単位確認する側制限を超えた場合
リクエスト
プロンプトの長さprompt2〜2,000文字当社が確認見積もりや保留の前に、promptに対して400 invalid_requestを返します。
画像サイズsize1K, 2Kデフォルト：1K–当社が確認sizeに対して400 invalid_requestを返します。
アスペクト比aspect_ratio16:9, 9:16, 1:1デフォルト：1:1–当社が確認aspect_ratioに対して400 invalid_requestを返します。
送信する画像
元画像image_urlなし–当社が確認編集モデルにはimage_urlが必要で、生成モデルはimage_urlを受け付けません：image_urlに対して400 invalid_requestを返します。
出力
出力ピクセル数1K16:91344×7689:16768×13441:11024×10242K16:92048×11529:161152×20481:12048×2048px当社が確認このサイズちょうどを指定してリクエストします。
出力の辺256〜2,048px（1辺あたり）提供元が確認上記のサイズはすべて範囲内です。これより大きいものは仕入れ先が拒否します。
出力形式JPEG–当社が確認すべての画像はJPEGです。
リンク
出力リンク24時間当社が確認期限を過ぎるとリンクは403を返します。ジョブを再度GETすると新しいリンクを取得できます。ファイル自体は12か月間保持されます（日付はジョブのoutputs_expire_at）。アセットに保存したもの、プロジェクトで使用中のものはそれ以降も保持されます。
qwen-image-edit-2511-lightning, qwen-image-edit-2511の制限
制限値単位確認する側制限を超えた場合
リクエスト
プロンプトの長さprompt2〜2,000文字当社が確認見積もりや保留の前に、promptに対して400 invalid_requestを返します。
画像サイズsize1K, 2Kデフォルト：1K–当社が確認sizeに対して400 invalid_requestを返します。
アスペクト比aspect_ratio16:9, 9:16, 1:1デフォルト：1:1–当社が確認aspect_ratioに対して400 invalid_requestを返します。
送信する画像
元画像image_urlちょうど1つ–当社が確認編集モデルにはimage_urlが必要で、生成モデルはimage_urlを受け付けません：image_urlに対して400 invalid_requestを返します。
アップロードサイズfile最大10MB当社が確認POST /v1/uploadsはfileに対して400 invalid_requestを返します。
アップロード形式fileJPEG, PNG, WebP–当社が確認ファイル名ではなく、ファイルの中身から判定します。それ以外の形式：fileに対して400 invalid_requestを返します。
出力
出力ピクセル数1K16:91344×7689:16768×13441:11024×10242K16:92048×11529:161152×20481:12048×2048px当社が確認このサイズちょうどを指定してリクエストします。
出力の辺512〜2,048px（1辺あたり）提供元が確認上記のサイズはすべて範囲内です。これより大きいものは仕入れ先が拒否します。
出力形式JPEG–当社が確認すべての画像はJPEGです。
リンク
アップロードリンク7日当社が確認期限を過ぎるとリンクは403を返します。ファイルを再度アップロードしてください。
出力リンク24時間当社が確認期限を過ぎるとリンクは403を返します。ジョブを再度GETすると新しいリンクを取得できます。ファイル自体は12か月間保持されます（日付はジョブのoutputs_expire_at）。アセットに保存したもの、プロジェクトで使用中のものはそれ以降も保持されます。

当社は他のホストから画像を取得しないため、そうしたリンクのサイズは仕入れ先が確認します。仕入れ先が拒否したジョブには課金されません。 同じ制限はJSONでも取得できます：GET /v1/modelsは、すべてのモデルについてlimitsオブジェクトを返します。

すべてのモデルの制限

料金をオープンに計算

画像1枚ごとに、モデルとサイズに応じたクレジット建ての価格です（US$1 = 100クレジット）。生成と編集は別々に価格が設定されています。

Qwen-Imageの価格
モデル1K2K
qwen-image-2512-lightning生成1 cr≈ $0.01$10で約1,000枚3 cr≈ $0.03$10で約333枚
qwen-image-edit-2511-lightning編集2 cr≈ $0.02$10で約500枚4 cr≈ $0.04$10で約250枚
qwen-image-2512生成2 cr≈ $0.02$10で約500枚6 cr≈ $0.06$10で約166枚
qwen-image-edit-2511編集3 cr≈ $0.03$10で約333枚10 cr≈ $0.10$10で約100枚
料金の算出方法

Webhookとべき等性

再試行で二重に課金されることはなく、ポーリングも不要です。

べき等性
生成のPOSTにはすべてIdempotency-Key（表示可能なASCII文字で1〜255文字）が必要です。24時間以内に同じキーを送るとHTTP 200で同じジョブが返されるため、タイムアウト後に再試行しても、2つ目のジョブが作成されたり課金されたりすることはありません。
拒否されたプロンプト
事前チェックで拒否されたプロンプト（422 content_rejected）では何も作成されないため、同じキーを新しいプロンプトで再利用できます。
イベント
job.queuedjob.processingjob.succeededjob.failedjob.cancelled
署名
X-Signatureには、UNIX時刻のtと、tとドットと生のボディをwhsec_シークレットで鍵付けしたHMAC-SHA256であるv1が含まれます。5分より古いタイムスタンプは拒否し、X-Event-Idで重複を排除してください。
配信
10秒以内に2xxが返れば配信済みとみなします。失敗した配信は、1 min、5 min、30 min、2 h、6 hの後に再試行されます。リダイレクトには従いません。
Webhookのボディ
{
  "id": "evt_01J9ZKB1QX",
  "type": "job.succeeded",
  "created_at": "2026-09-29T14:02:31Z",
  "data": {
    "job": {
      "id": "job_01J9ZK4T8W",
      "object": "job",
      "kind": "image",
      "status": "succeeded",
      "money_status": "settled",
      "requested_model": "qwen-image-2512",
      "credits_charged": 2,
      "outputs": [
        {
          "kind": "image",
          "url": "https://…/job_01J9ZK4T8W.png?sig=…"
        }
      ]
    }
  }
}
X-Signatureを検証
import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the request body exactly as received, before any JSON parsing.
export function verifyWebhook(header, rawBody, secret, toleranceSec = 300) {
  let t = null;
  const signatures = [];
  for (const item of (header ?? "").split(",")) {
    const [key, value] = item.split("=", 2);
    if (key === "t") t = Number(value);
    if (key === "v1") signatures.push(Buffer.from(value, "hex"));
  }
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  return signatures.some((s) => s.length === expected.length && timingSafeEqual(s, expected));
}

// verifyWebhook(req.headers["x-signature"], rawBody, process.env.WEBHOOK_SECRET)
// Answer 2xx quickly, and skip an X-Event-Id you have already handled.

エラーと対処法

すべてのエラーは同じ形式です：code、message、param、request_idを含むerrorオブジェクト。よく発生するものは次のとおりです：

コードHTTP対処法
invalid_request400paramに示されたフィールドを修正してください。
unauthorized401キーとBearerヘッダーを確認してください。
insufficient_credits402チャージしてから、同じIdempotency-Keyで再試行してください。
forbidden_model403スタジオでキーの許可リストにモデルまたはツールを追加するか、別のキーを使用してください。高画質化などのツールには、個別の登録が必要です。
quote_expired409新しい見積もりを取得してください。見積もりの有効期間は10分です。
price_changed409価格が上限を超えました。再度見積もるか、max_creditsを引き上げてください。
content_rejected422課金はされていません。プロンプトまたは画像を変更してください。
rate_limited429Retry-Afterの時間だけ待ってから、再試行してください。
upstream_unavailable503モデルを利用できません。後で再試行してください。開始されなかったジョブには課金されません。
OpenAPI 3.1ドキュメント llms.txt ドキュメント全体 fal・Replicate・WaveSpeedからの移行