aisplice

API リファレンス

画像：非同期タスク

このエンドポイントのモデル（12）

gpt-image-2.5-extgpt-image-2seedream-5-0-flashgpt-image-2.5-flare+8
ワークベンチで試す
POST/v1/images/tasks
GET/v1/images/tasks/{task_id}
GET/v1/images/tasks/{task_id}/content

非同期の画像生成 — モデル一覧のすべての画像モデルが使うルートです。送信すると task_id が返ります。ステータスエンドポイントをポーリングし、/content から永続的な結果 URL を読み取ります — または Webhook を登録すればポーリングは不要です。

#リクエストパラメーター

  • modelstring必須

    非同期画像モデルの ID（例：gpt-image-2）。同期専用モデルはこのエンドポイントを拒否します。

  • promptstring必須

    描きたい内容。

  • sizestring任意

    アスペクト比のプリセット（例："16:9"）。ほとんどの画像モデルはこの形式で、指定できる値はモデルカードに記載されています。一部の古いモデルは WIDTHxHEIGHT も受け付けます。

  • resolutionstring任意

    出力解像度のティア（例："1K"、"2K"、"4K"）。モデルカードに記載がある場合に指定できます — これも料金ティアの軸の 1 つです。

  • qualitystring任意

    ベンダーの品質レベル（例：standard / hd） — これも料金ティアの軸の 1 つです。

  • ninteger任意

    画像の枚数（枚数分の料金がかかります）。

  • imagesarray任意

    編集または参照する画像。URL か data URI で指定します。受け付ける枚数はモデルカードで確認してください。

  • maskstring任意

    最初の参照画像の一部だけを描き直します。下の「画像の一部だけを編集」を参照してください。モデルカードに mask があるモデルだけが受け付けます。mask_url と書いても同じです。

  • webhook_urlstring任意

    タスクが終了状態になったときに呼び出される HTTPS URL — コールバックの仕様は動画ガイドを参照してください。

  • webhook_secretstring任意

    設定すると、配信に X-Xiaoxiang-Signature: sha256=hex(HMAC-SHA256(body, secret)) が付きます。

パラメーターはモデルごとに異なります

各モデルが受け付けるフィールドと値はモデルカードで確認してください。gpt-image-2.5-ext では size に比率を指定し、resolution と組み合わせます。2560x1088 のようなピクセルサイズは、最も近い比率と解像度（21:9、2K）に置き換えられます。background は設定できません。"auto" は無視され、それ以外の値は拒否されます。1 回のリクエストで 1 枚だけ生成し、version は選べません。省略するか "flare" を指定してください。

フィールド名はモデルファミリーによって異なる場合があります

タスクステータスのペイロードは上流ベンダーの報告内容をそのまま反映します。実際のレスポンスを正とし、ベンダーをまたいで安定している task_id、status、/content エンドポイントに依拠してください。

#画像の一部だけを編集

images に元画像を入れ、mask を送ると、マスクで指定した部分だけが描き直され、それ以外はそのまま残ります。その部分に何を描くかは prompt に書きます。現在 mask に対応しているのは gpt-image-2.5-flare と gpt-image-2.5-sunburst で、モデルカードには mask フィールドとして表示されます。

curl https://www.aisplice.store/v1/images/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "Replace the mug with a glass of orange juice; keep everything else",
    "images": ["https://example.com/desk.png"],
    "mask": "https://example.com/desk-mask.png",
    "resolution": "1K"
  }'

マスクの作り方

アルファチャンネル付きの PNG を使います。完全に透明なピクセルが描き直す部分で、それ以外は残ります。サイズは最初の参照画像のピクセルサイズと完全に同じにし（出力サイズではありません）、4 MB 未満にしてください。マスクは 1 リクエストにつき 1 枚で、参照画像が複数あるときは最初の 1 枚に適用されます。gpt-image-2.5 モデルでは size を省略すると、元画像の縦横比が保たれます。
  • 400 invalid_request参照画像なしで mask を送ったか、mask に対応していないモデルに送りました（gpt-image-2.5-ext は "mask is not supported on Ext" を返します）。

エラーコード一覧 →

#関連するエラー

  • 404 not_found不明なパス、不明なモデル名、または期限切れか他アカウントの task_id です。
  • 401Bearer トークンが無効か、ありません。このパスでは error.code が付きません — ステータスで判定してください。
  • 402 insufficient_user_quotaウォレット残高が事前確保の見積額に足りません。
  • 429キー単位のレート制限です。ボディは空なので、Retry-After の時間だけ待ってください。insufficient_user_quota が付いた 429 は、レート制限ではなく 1 日の利用上限額によるものです。
  • 503 model_not_found不明なモデルか、現在そのモデルを提供できる正常なチャネルがありません。

エラーコード一覧 →

#リクエスト例

# 1. submit
curl https://www.aisplice.store/v1/images/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2.5-ext", "prompt": "A red paper crane on a desk", "size": "16:9", "resolution": "1K"}'

# 2. poll every 3s until a terminal status
curl https://www.aisplice.store/v1/images/tasks/$TASK_ID -H "Authorization: Bearer sk-YOUR_KEY"

# 3. fetch persistent result URLs
curl https://www.aisplice.store/v1/images/tasks/$TASK_ID/content -H "Authorization: Bearer sk-YOUR_KEY"

#レスポンス

response.json
// POST /v1/images/tasks
{"task_id": "task_xxx", "status": "queued"}

// GET /v1/images/tasks/{task_id}
{"task_id": "task_xxx", "status": "in_progress", "progress": "60%"}

// GET /v1/images/tasks/{task_id}/content — after completion
{"created": 1720000000, "data": [{"url": "https://…"}]}

まだ解決しませんか？

リクエスト ID かエラーメッセージを送っていただければ、こちらで調査します。

前へMessages（Anthropic 形式）次へ動画