GPT Image 2

POST https://api.beatapi.io/v1/images/tasks

テキストと最大 16 枚の公開 HTTPS 参照画像を使って画像を生成・編集します。最大 4K の出力に対応しています。

対応する生成モード

非同期処理の流れ： タスクを作成して data.id を保存し、GET /v1/tasks/{task_id} でステータスをポーリングします。succeeded の場合は data.output.media から結果を取得します。failed の場合は data.error_code と data.error_message を確認し、エラーと再試行の方針に従って対処してください。

ローカルファイルを使う場合： 先に入力ファイルをアップロードし、返された data.url を指定してください。

認証

Authorization   string   必須

BeatAPI の API キーを Bearer トークンとして送信します。API キーはダッシュボードで作成できます。

Authorization: Bearer <BEATAPI_API_KEY>

通常の API キーは、信頼できるサーバーで管理してください。リクエストボディには Content-Type: application/json が必要です。対応するエンドポイントでは Idempotency-Key は任意ですが、同一のリクエストボディで安全に再試行するために指定を推奨します。

リクエストボディ

model   string   必須

gpt-image-2 を指定してください。

固定値: gpt-image-2

prompt   string   必須

画像の生成・編集の指示です。

文字数: 1 – 5000 文字

images   string[]   任意

公開 HTTPS URL で参照できる PNG・JPEG・WebP 画像を指定します。タスク作成時に各 URL が検証され、対応する画像でない場合（エラーページ、GIF、404 など）は HTTP 400 で拒否されます。テキストから生成する場合は省略してください。

要素数: 1 – 16 件

aspect_ratio   enum<string>   任意

出力画像のアスペクト比です。resolution と aspect_ratio の組み合わせ、または size のいずれかを指定してください。両方は指定できません。

選択肢: auto, 1:1, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 16:9, 9:16, 2:1, 1:2, 3:1, 1:3, 21:9, 9:21
デフォルト値: "auto"

resolution   enum<string>   任意

出力解像度の区分です。size と同時には指定できません。

選択肢: 1K, 2K, 4K
デフォルト値: "1K"

size   string   任意

出力サイズを 幅x高さ（例：1536x1024、3840x2160）で指定します。resolution と aspect_ratio の代わりに使うフィールドで、どちらかを同時に送ると HTTP 400 になります。幅・高さは 16 の倍数で 16～3840 px、総画素数は 655,360～8,294,400、長辺は短辺の 3 倍以内にしてください。2,097,152 画素以下は 1K、5,898,240 画素以下は 2K、それを超える場合は 4K として課金されます。

background   enum<string>   任意

出力の背景です。transparent はアルファチャンネル付きの PNG を返します。プロンプトには、被写体を単独で配置し背景を透明にすることを明記してください。opaque は背景を塗りつぶし、auto はモデルに選択を任せます。

選択肢: auto, opaque, transparent
デフォルト値: "auto"

リクエスト例

テキストから画像を生成

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header 'Authorization: Bearer <BEATAPI_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "gpt-image-2",
  "prompt": "A clean campaign image with soft studio lighting.",
  "aspect_ratio": "1:1",
  "resolution": "1K"
}'

参照画像を使用

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header 'Authorization: Bearer <BEATAPI_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "gpt-image-2",
  "prompt": "Create a clean campaign image from the supplied product reference.",
  "images": [
    "https://media.beatapi.io/samples/smart-bottle.png"
  ],
  "aspect_ratio": "1:1",
  "resolution": "2K"
}'

レスポンス

リクエストが成功すると、HTTP 201 が返されます。

{
  "data": {
    "id": "task_8K2qA",
    "object": "task",
    "task_kind": "image",
    "capability_id": "gpt-image-2",
    "capability_version": null,
    "media_type": "image",
    "model": "gpt-image-2",
    "status": "queued",
    "stage": "queued",
    "created_at": 1782210000,
    "updated_at": 1782210000,
    "completed_at": null,
    "output": null,
    "usage": {
      "credits_reserved": 0.04,
      "credits_charged": 0.04,
      "credits_settled": 0,
      "credits_refunded": 0
    },
    "request_id": "req_abc123",
    "error_code": null,
    "error_message": null
  }
}

エラー