API リファレンス

公開 REST API の完全スキーマ。Pro および Max プランで利用できます。キーは /account/api から発行してください。

Postman をお使いですか? v2.1 コレクションをダウンロード — gimg_… キーを apiKey 変数に貼り付けてください。

認証

すべてのエンドポイントは Authorization ヘッダーに Bearer トークンを必要とします。トークンは必ず gimg_ で始まります。

Authorization: Bearer gimg_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

レート制限

キーあたり 600 リクエスト / 時間、同時実行 5 件まで。すべてのレスポンスに以下が含まれます:

X-RateLimit-Limit — 600 で固定
X-RateLimit-Remaining — 現在のウィンドウで残っている呼び出し回数
X-RateLimit-Reset — ウィンドウがリセットされる epoch 秒
Retry-After — 次の呼び出しが許可されるまでの秒数 (429 の場合のみ)

冪等性

POST リクエストには Idempotency-Key を渡してください。同じキーを 2 回送信すると、クレジットを二重請求せず既存の生成行を返します。

POST/api/v1/generate

テキストから画像生成、または画像編集を送信します。即座に generationId を返します。/api/v1/generations/:id をポーリングして結果を取得してください。

Body

promptstring ≤ 4000 chars必須
自然言語による説明。写真用語 (カメラ、レンズ、ライティング) があると効果的です。
type"text2img" | "edit"
デフォルトは 'text2img'。'edit' には inputImageKeys が必要です。
size"1024x1024" | "1024x1536" | "1536x1024"
アスペクト比。デフォルトは 1024x1024。
quality"low" | "medium" | "high"
デフォルトは medium。high = HD 2K。low は Fast (1cr)。
n1–4
バリエーション数。デフォルトは 1。
inputImageKeysstring[] (max 4)
/api/v1/upload が返す R2 キー。type=edit の場合に必須。

Responses

202 Acceptedjson
{ "generationId": "...", "status": "queued" }
400 Bad Requestjson
Body が無効。エラーには Zod 検証メッセージが含まれます。
401 Unauthorizedjson
Bearer キーが欠落または無効です。
402 Payment Requiredjson
クレジット不足、または月間コンピュート上限に到達しました。
403 Forbiddenjson
Pro / Max プランが必要です。
422 Unprocessablejson
プロンプトがコンテンツポリシーによりブロックされました。
429 Too Many Requestsjson
レート制限に達しました。Retry-After を参照してください。

POST/api/v1/upload

入力画像をアップロードするための署名付き R2 PUT URL を取得します。2 ステップ方式です: このエンドポイントが URL を返すので、その URL に直接バイトを PUT してください。

Body

filenamestring ≤ 200必須
表示名。ストレージには使用されません。
contentType"image/png" | "image/jpeg" | "image/webp"必須
この 3 つのうちのいずれか 1 つでなければなりません。
sizenumber (bytes ≤ 10 MB)必須
PUT する予定のファイルサイズ。検証に使用されます。

Response (200)

urlstring
署名付き PUT URL。5 分で失効します。
keystring
R2 キー — /api/v1/generate を呼び出す際に inputImageKeys に渡してください。

GET/api/v1/generations/:id

生成のステータスをポーリングします。即座に現在の状態を返します。

Response (200)

idstring
生成 ID。
status"queued" | "running" | "succeeded" | "failed" | "blocked"
'blocked' = コンテンツモデレーションが入力または出力を拒否しました (クレジットは返金されます)。
typestring
text2img | edit | upscale | …
outputsArray<{ png, webp, width, height }>
status=succeeded のときに値が入ります。URL は公開・不変・CDN キャッシュされます。
errorstring | null
status=failed または status=blocked のときに値が入ります。
costCreditsnumber
請求されたクレジット (blocked または failed の場合は返金)。
createdAt / completedAtISO 8601
タイムスタンプ。

アウトバウンド Webhook

ポーリングは不要です: HTTPS エンドポイントを登録すると、generation.succeeded や generation.failed イベントが発生時に届きます。/api/account/webhooks から管理してください。

登録

curl -X POST https://gptimage2.plus/api/account/webhooks \
  -H "Cookie: <your session cookie>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/hooks/gptimg",
    "events": ["generation.succeeded", "generation.failed"],
    "label": "Production app"
  }'
# → { "id": "...", "secret": "whsec_..." }   ← copy this, shown ONCE

イベントペイロード

POST https://your-app.com/hooks/gptimg
X-Gptimg-Event: generation.succeeded
X-Gptimg-Signature: <hex sha256 hmac of body>
X-Gptimg-Delivery: <uuid for dedup>
Content-Type: application/json

{
  "event": "generation.succeeded",
  "data": {
    "generationId": "...",
    "type": "text2img",
    "status": "succeeded",
    "outputs": [{ "png": "...", "webp": "...", "width": 1024, "height": 1024 }],
    "createdAt": "2026-04-26T01:23:45.000Z",
    "completedAt": "2026-04-26T01:23:50.000Z"
  }
}

署名の検証

// Node example
import crypto from "crypto";
const expected = crypto
  .createHmac("sha256", process.env.WEBHOOK_SECRET)
  .update(rawBody)
  .digest("hex");
const ok = crypto.timingSafeEqual(
  Buffer.from(expected),
  Buffer.from(req.headers["x-gptimg-signature"])
);

タイムアウト: 試行ごとに 5 秒。2xx 以外のレスポンスには指数バックオフ (30 秒 → 2 分 → 10 分) で最大 3 回リトライします。8 回連続で失敗すると Webhook は自動的に無効化されます — /account/webhooks から再有効化してください。