GPT Image 2.6 Flare Beta | BeatAPI API Documentation

テキストと最大 16 枚の参照画像から、1K・2K・4K、または正確なピクセルサイズの画像を生成または編集します。プロンプトだけから短い GIF アニメーションも作れます。

非同期です。作成の呼び出しはすぐにタスク ID を返し、画像はタスクが成功した時点で得られます。
1 タスクにつき画像は 1 枚です。複数枚が必要な場合は、複数のタスクを作成してください。
テキストから画像を生成するほか、公開 HTTPS リンクで指定した最大 16 枚の参照画像を編集・合成できます。
画面の形は resolution と aspect_ratio で指定するか、1536x1024 のような正確な size 1 つで指定します。両方を同時に使うことはできません。
静止画はサイズ区分（1K、2K、4K）ごとの料金です。output_format: "gif" はプロンプトだけから短いアニメーションを作り、GIF 1 枚ごとに課金されます。失敗したタスクには課金されません。

GPT Image 2.6 Flare Beta は、OpenAI の小型で高速な GPT Image 2.6 モデルの固定価格ラインです。静止画はサイズ区分ごとに 1 枚いくら、GIF は 1 枚いくらの料金です。リクエストは GPT Image 2.5 Flare から background を除いたもので、短い GIF アニメーションも作れる output_format が加わっています。トークン課金で、quality や GIF のフレームサイズを指定したい場合は gpt-image-2.6-flare を使ってください。

POST/v1/images/tasks試してみる

このモデルをテスト画面で開きます。BeatAPI の API キーを入力するとタスクを作成できます。実際に呼び出され、ご自身の残高から課金されます。

モデル ID

2 つの GPT Image 2.6 モデルは、同じエンドポイントと同じフィールドを使います。以下の値はゲートウェイの仕様から直接取得したものです。

モデル ID	`resolution`	`images` の最大数	`output_format`	概要
`gpt-image-2.6-flare-beta`	`1K`, `2K`, `4K`	16	`png`, `gif`	OpenAI の GPT Image 2.6 のうち、小型で高速なモデルです。価格は料金表をご覧ください。
`gpt-image-2.6-sunburst-beta`	`1K`, `2K`, `4K`	16	`png`, `gif`	GPT Image 2.6 の基本モデルで、より細部まで描き込みます。フィールドと制限は Flare と同じです。価格は料金表をご覧ください。

エンドポイントと認証

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

`Authorization` string 必須

BeatAPI の API キーを Bearer <BEATAPI_API_KEY> の形式で送信します。キーはダッシュボードで作成できます。キーはサーバー側で保管し、ブラウザーやモバイルアプリに含めないでください。

ボディは JSON で送信し、Content-Type: application/json を指定します。Idempotency-Key は任意です。論理的に 1 件のリクエストごとに一意の値（255 文字以内）を送り、まったく同じボディを再試行するときだけ再利用してください。24 時間以内に同じキーと同じボディで再試行すると、最初のレスポンスが Idempotent-Replayed: true 付きで再度返されます。同じキーで異なるボディを送ると 409 idempotency_conflict が返ります。2xx 以外のレスポンスは保存されないため、400 や 402 の後の再試行は改めて実行されます。

リクエストの流れ

タスクを作成する

下記のパラメーターをエンドポイントに POST します。201 が返れば、タスクが受け付けられ、料金が残高から仮確保されたことを意味します。処理はバックグラウンドで実行されます。data.id を保存してください。

完了を待つ

GET /v1/tasks/{task_id} を呼び出し、status が succeeded または failed になるまで、呼び出しの間隔を data.poll_after_seconds（画像は 5 秒、動画は 8 秒）だけ空けてください。あるいは task.succeeded と task.failed のWebhookを登録することもできます。処理タイムアウトで停止したタスクはイベントを送信しないため、フォールバックとしてポーリングも続けてください。

結果を保存する

succeeded の場合は、すべての data.output.media[].url をダウンロードし、必要なファイルを保存してください。結果 URL がいつまで利用できるかは保証されません。failed の場合は、data.error_code と data.error_message を確認してください。仮確保された金額は残高に戻されます。data.retryable は、同じリクエストをもう一度送れば成功する可能性があるかどうかを示します。

入力モード

モード	必須の入力	備考
テキストから画像	`model`、`prompt`	`images` は省略してください。
画像の編集・合成	`model`、`prompt`、`images`	公開 HTTPS の画像リンクを 1～16 個指定します。変更・維持・合成したい内容を `prompt` に記述してください。
GIF アニメーション	`model`、`prompt`、`output_format`	`"output_format": "gif"` を送り、`images`、`size`、`resolution`、`aspect_ratio` は省略してください。

リクエストパラメーター

`model` string 必須

実行するモデルです。

値：gpt-image-2.6-flare-beta

値が正しくない場合

指定がない場合："model" is required
不明なモデル ID の場合："model" gpt-image-9 is not catalogued
動画モデルをこのエンドポイントに送った場合："model" seedance-2.5 is served by POST /v1/videos/tasks, not this endpoint

`prompt` string 必須

描きたい内容、または参照画像に加えたい変更です。被写体、スタイル、照明、構図、画像内に表示したい文字などを、普通の言葉で書くのが最適です。

長さ：1–5000 文字

長さは文字数で数えます（CJK 文字も 1 文字として数えます）。
images を送る場合は、どの画像が何の役割かを書いてください。たとえば「1 枚目の画像を商品に、2 枚目の画像を背景に使う」のように指定します。
GIF ではプロンプトが唯一の入力です。被写体と動きを書いてください。

値が正しくない場合

指定がない場合："prompt" is required
空、または上限を超える長さの場合："prompt" has an unsupported length
文字列でない場合："prompt" must be a string

`images` string[] 任意

編集または合成する参照画像です。このフィールドを送ると、リクエストはテキストからの画像生成ではなく、画像編集として扱われます。

要素数：1–16
各要素は公開されている https:// の URL です。ローカルファイルは先にアップロード（POST /v1/files）し、返された data.url を渡してください。

各リンクは、公開 HTTPS で画像ファイルそのもの（PNG、JPEG、WebP）を返し、サイズが 50 MB 以下である必要があります。ゲートウェイは、タスクを作成する前に、すべてのリンクの先頭バイトをダウンロードし、ファイル名や Content-Type ではなく、そのバイト列から形式を判定します。
Web ページ、ログインが必要なページ、期限切れの署名付き URL、ホットリンク保護のあるホストへのリンクは、画像を返さないため拒否されます。
エラーメッセージ中の位置は 0 始まりです。images[0] は 1 番目のリンクを指します。
output_format: "gif" とは同時に使えません。GIF はプロンプトだけから作られます。

値が正しくない場合

最大数を超えた場合："images" accepts at most 16 items
空の配列の場合："images" requires at least 1 item
https:// のリンクでない場合："images[0]" must be a public HTTPS URL
プライベートまたは安全でないアドレスの場合："images[0]" must be a publicly reachable HTTPS image URL
ホストが 4xx エラーを返した場合："images[0]" could not be downloaded: the URL returned HTTP 404
リンクが PNG、JPEG、WebP 以外を返した場合："images[0]" is not a PNG, JPEG or WebP image: the URL returned text/html
50 MB を超える場合："images[2]" is 63.4 MB; images must be 50 MB or smaller
output_format: "gif" と同時に送った場合：gpt-image-2.6-flare-beta output_format "gif" is made from the prompt alone: leave out "images"

例

"images": [
  "https://cdn.beatapi.io/samples/smart-bottle.png",
  "https://cdn.beatapi.io/samples/neon-singer.png"
]

`aspect_ratio` string 任意デフォルト: `auto`

画像の形を「幅:高さ」で指定します。resolution と一緒に送るか、両方を省略して 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

デフォルトは auto なので、このフィールドを省略したリクエストも正方形で描画されます。
2:1、1:2、3:1、1:3、21:9、9:21 といったパノラマ形状も指定できます。最も横長または縦長のフレームは 3:1 です。
size と同時には使えません。
output_format: "gif" では省略してください。GIF のフレームはモデルが決めます。その場合に受け付けるのはデフォルトの auto だけです。

auto は「参照画像の形に従う」という意味ではありません。images の有無にかかわらず、選択した resolution の正方形のフレームを要求します。編集結果を別の形にしたい場合は、比率を指定するか、size を送ってください。

値が正しくない場合

一覧にない値の場合："aspect_ratio" must be one of: [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]
size と同時に送った場合："size" already fixes the output; do not send "aspect_ratio" with it
output_format: "gif" で auto 以外を送った場合：gpt-image-2.6-flare-beta output_format "gif" has a fixed size: leave out "aspect_ratio"

`resolution` string 任意デフォルト: `1K`

画像のサイズ区分です。区分が高いほど画像は大きくなり、料金も上がります。正確なピクセルサイズは aspect_ratio に依存し、モデルが決定します。

指定できる値：1K, 2K, 4K
デフォルト：1K

大文字の K を使ってください。2k は拒否されます。
このページでは、区分ごとの正確なピクセル寸法は保証しません。正確なフレームが必要な場合は size を送ってください。
size と同時には使えません。size は独自のサイズを持ち、ピクセル数に応じて課金されます。
output_format: "gif" では省略してください。GIF には独自のサイズと料金があります。その場合に受け付けるのはデフォルトの 1K だけです。

値が正しくない場合

一覧にない値の場合："resolution" must be one of: [1K 2K 4K]
size と同時に送った場合："size" already fixes the output; do not send "resolution" with it
output_format: "gif" で 1K 以外を送った場合：gpt-image-2.6-flare-beta output_format "gif" has a fixed size: leave out "resolution"

`size` string 任意

ピクセル単位の正確な出力サイズを WIDTHxHEIGHT の形式で指定します。例：1536x1024。resolution と aspect_ratio の代わりになります。

両方の辺が 16 の倍数で、16～3840 px の範囲内である必要があります。
合計ピクセル数は 655,360～8,294,400 の範囲内で、長辺は短辺の 3 倍以下にしてください。
区切り文字には x、X、× を使えます。前後のスペースは無視されます。
価格区分はピクセル数で決まります。2,097,152 ピクセル以下は 1K、5,898,240 以下は 2K、それを超えると 4K です。例は下の表「size の課金方法」をご覧ください。
resolution や aspect_ratio は、デフォルト値であっても一緒に送らないでください。
output_format: "gif" とは同時に使えません。

size は送信した値のとおりに検証・課金されますが、納品される画像のピクセル数がその値と完全に一致することは、このページでは保証しません。正確な寸法がパイプラインに必要な場合は、保存されたファイルを読み取ってください。

値が正しくない場合

文字列でない場合："size" must be a string
WIDTHxHEIGHT の形式でない場合（数字だけ、auto、カンマなど）："size" must be WIDTHxHEIGHT in pixels, for example 1536x1024
辺が 16 の倍数でない場合："size" width and height must be multiples of 16
辺が 16 未満または 3840 を超える場合："size" edges must be between 16 and 3840 pixels
ピクセル数が少なすぎる、または多すぎる場合："size" must have between 655,360 and 8,294,400 pixels; 512x512 has 262,144
3:1 より横長または縦長の場合："size" must not be wider or taller than 3:1
resolution と同時に送った場合："size" already fixes the output; do not send "resolution" with it
aspect_ratio と同時に送った場合："size" already fixes the output; do not send "aspect_ratio" with it
output_format: "gif" と同時に送った場合：gpt-image-2.6-flare-beta output_format "gif" has a fixed size: leave out "size"

例

"size": "1536x1024"

`output_format` string 任意デフォルト: `png`

作成するファイルの種類です。png は静止画、gif は短いアニメーションです。

指定できる値：png, gif
デフォルト：png

png（デフォルト）は、指定した resolution、aspect_ratio、size で静止画を生成し、サイズ区分ごとに課金されます。
gif は短いアニメーションを作ります。サイズ（約 300～1024 px）とフレーム数はモデルが決めます。size、resolution、aspect_ratio は一緒に送らないでください。
GIF はプロンプトだけから作られます。images は使えず、frame_count と frame_duration_ms にも対応していません。
GIF はサイズにかかわらず、GIF 1 枚ごとの独自の料金で課金されます。料金表をご覧ください。
このページでは、アニメーションがループ再生されることは保証しません。

値が正しくない場合

一覧にない値の場合："output_format" must be one of: [png gif]
gif と images を同時に送った場合：gpt-image-2.6-flare-beta output_format "gif" is made from the prompt alone: leave out "images"
gif と size を同時に送った場合：gpt-image-2.6-flare-beta output_format "gif" has a fixed size: leave out "size"

例

"output_format": "gif"

ゲートウェイはタスク作成前に、次の組み合わせも確認します。

size は 幅x高さ で指定し、resolution と aspect_ratio の代わりに使用します。各辺は 16 の倍数で 16～3840 ピクセル、総画素数は 655,360～8,294,400、長辺と短辺の比は 3:1 以下です。
指定サイズは総画素数で課金されます。2,097,152 以下は 1K、5,898,240 以下は 2K、それ以上は 4K の料金です。
output_format: gif は短いアニメーションを作ります。サイズ（約 300～1024 ピクセル）とフレーム数はモデルが決めます。size、resolution、aspect_ratio は一緒に送らないでください。
GIF はプロンプトだけから作られます。images は使えず、frame_count と frame_duration_ms にも対応していません。
GIF は 1 枚ごとに GIF 独自の料金で課金されます。png は 1 枚ごとに解像度区分の料金で課金されます。
gpt-image-2.6-flare は公式版で、トークン課金です。quality に low、medium、high、xhigh、max、および任意サイズの GIF を指定できます。このモデルでは使えません。

入力メディアの上限

ゲートウェイはタスク作成前にすべての入力を読み取り、次の上限を超えるものは、その入力を示す 400 bad_request で拒否します。課金はされません。

参照画像：PNG、JPEG、WebP。ファイルの内容から判定されます。1 件あたり 50 MB 以下（10 進の MB。ホストがサイズを申告した場合に確認されます）で、リンクは 1～16 個です。GIF、HEIC、SVG は拒否されます。
参照画像そのもののピクセル数やアスペクト比の上限は確認されません。
ホストが時間内に応答しない場合、そのリンクは作成時には拒否されません。ゲートウェイはタスクのディスパッチ時に再度取得を試み、それでも取得できないリンクがあるとタスクは失敗し、返金されます。
ローカルファイルは POST /v1/files でアップロードし、返された data.url を指定してください。
GIF（output_format: "gif"）は参照画像を受け付けません。

フレームの選び方：`resolution` と `aspect_ratio`、または `size`

画像の大きさと縦横の比を指定する方法は 2 つあり、同時には使えません。

区分と比率。 resolution（1K、2K、4K）を送り、形を指定したい場合は aspect_ratio も送ります。両方を省略すると 1K と auto、つまり正方形のフレームになります。
正確なサイズ。 size だけを送ります。例：1536x1024。ピクセル数に応じて課金されます（下の表）。

size を resolution または aspect_ratio と一緒に送ると、"size" already fixes the output; do not send "resolution" with it（または "aspect_ratio"）で拒否されます。このチェックは、もう一方のフィールドがデフォルト値であっても適用されます。

GIF ではどちらも使いません。フレームはモデルが決めます。

GIF アニメーションを作る

"output_format": "gif" を送り、prompt に被写体と動きを書きます。結果は短い GIF アニメーションです。

プロンプトだけから作ります。 images は gpt-image-2.6-flare-beta output_format "gif" is made from the prompt alone: leave out "images" で拒否されます。
フレームはモデルが決めます。 サイズは約 300～1024 px で、フレーム数もモデルが決めます。size、resolution、aspect_ratio は省略してください。size を送った場合、1K 以外の resolution や auto 以外の aspect_ratio を送った場合は、gpt-image-2.6-flare-beta output_format "gif" has a fixed size: leave out "size"（送ったフィールド名が入ります）で拒否されます。
フレームの指定はできません。 frame_count と frame_duration_ms には対応していません（unknown field: frame_count）。
独自の料金です。 GIF はサイズ区分ではなく、下の料金表にある GIF の料金で 1 枚ごとに課金されます。

このページでは、アニメーションがループ再生されることは保証しません。保存されたファイルの mime_type は image/gif です。

このモデルが受け付けないフィールド

画像エンドポイントは、他の画像モデルや他の API が使ういくつかのフィールドを認識します。ここでそれらを送ると、無視されずに拒否されます。そのため、効果のなかった設定に対して料金を支払うことはありません。

background、quality、seed、enhance_prompt → field "background" is not supported by model gpt-image-2.6-flare-beta（送信したフィールド名と呼び出したモデル名が入ります）。GPT Image 2.6 には background フィールドがないため、透明な背景は指定できません。
それ以外の未知のフィールド（たとえば n、moderation、frame_count）→ unknown field: n。n はありません。1 タスクで作られるのは画像 1 枚または GIF 1 枚です。

`size` の課金方法

size は、ピクセル数が属する区分の価格で課金されます。以下の例はこの規則にそのまま従っています。2,097,152 ピクセル以下は 1K、5,898,240 以下は 2K、それを超えると 4K です。

`size`	ピクセル数	課金区分
`1024x1024`	1,048,576	1K
`1536x1024`	1,572,864	1K
`2048x1152`	2,359,296	2K
`2560x1440`	3,686,400	2K
`2048x2048`	4,194,304	2K
`2880x2880`	8,294,400	4K
`3840x2160`	8,294,400	4K

リクエスト例

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.6-flare-beta",
  "prompt": "A minimalist product photo of a glass water bottle on wet black stone, soft rim light, shallow depth of field",
  "aspect_ratio": "3:2",
  "resolution": "2K"
}'

テキストから画像

区分と比率を指定して、プロンプトから 2K の横長画像を生成します。

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.6-flare-beta",
  "prompt": "A minimalist product photo of a glass water bottle on wet black stone, soft rim light, shallow depth of field",
  "aspect_ratio": "3:2",
  "resolution": "2K"
}'

1 枚の画像を編集

商品はそのままに、背景を変更します。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.6-flare-beta",
  "prompt": "Keep the bottle exactly as it is. Replace the background with a sunlit kitchen counter and add a soft reflection under the bottle.",
  "images": [
    "https://cdn.beatapi.io/samples/smart-bottle.png"
  ],
  "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.6-flare-beta",
  "prompt": "Place the bottle from the first image on a neon-lit stage like the one in the second image. Keep the bottle label readable.",
  "images": [
    "https://cdn.beatapi.io/samples/smart-bottle.png",
    "https://cdn.beatapi.io/samples/neon-singer.png"
  ],
  "aspect_ratio": "16:9",
  "resolution": "2K"
}'

正確なサイズ

1536x1024 のフレームです。size は単独で使います。resolution も aspect_ratio も送りません。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.6-flare-beta",
  "prompt": "A flat illustration of a lighthouse on a cliff at dawn, pastel colours, clean shapes",
  "size": "1536x1024"
}'

GIF アニメーション

プロンプトだけから短いアニメーションを作ります。images、size、resolution、aspect_ratio は送りません。GIF の料金で課金されます。

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.6-flare-beta",
  "prompt": "A paper boat drifting on gentle blue waves, flat illustration, soft morning light",
  "output_format": "gif"
}'

レスポンス

タスクの作成（201）

タスクオブジェクトです。タスクが成功するまで output は null です。「実行中」と記載されたフィールドは、タスクの完了後に表示されなくなります。

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "image",
    "capability_id": "gpt-image-2.6-flare-beta",
    "capability_version": 1,
    "media_type": "image",
    "model": "gpt-image-2.6-flare-beta",
    "status": "queued",
    "stage": "queued",
    "created_at": 1791993600,
    "updated_at": 1791993600,
    "completed_at": null,
    "poll_after_seconds": 5,
    "output": null,
    "usage": {
      "credits_reserved": 0.022,
      "credits_settled": 0,
      "credits_refunded": 0,
      "credits_charged": 0.022
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

フィールド	型	説明
`data.id`	`string`	タスク ID です。`task_` の後に英数字 32 文字が続きます。ポーリングや Webhook イベントとの照合に使います。
`data.object`	`string`	常に `task` です。
`data.task_kind`	`string`	`image` または `video` です。
`data.capability_id`	`string`	送信したモデル ID です。
`data.capability_version`	`integer`	モデルの仕様バージョンです。現在は `1` です。
`data.media_type`	`string`	`image` または `video` です。
`data.model`	`string`	送信したモデル ID です（`capability_id` と同じ）。
`data.status`	`string`	`queued`、`processing`、`succeeded`、`failed` のいずれかです。最終状態は後ろの 2 つだけです。
`data.stage`	`string`	`status` と同じ値です。古いクライアント向けに残されています。
`data.created_at`	`integer`	タスクの作成日時（Unix 秒）です。
`data.updated_at`	`integer`	最終更新日時（Unix 秒）です。
`data.completed_at`	`integer \| null`	タスクの完了日時（Unix 秒）です。実行中は `null` です。
`data.poll_after_seconds`	`integer`	実行中のみ。次のポーリングまでに待つ秒数です（画像は 5、動画は 8）。
`data.typical_seconds`	`object`	実行中のみ、直近のタスクが十分にある場合に含まれます。直近 `window` の `samples` 件のタスクについて、完了までの時間（秒）の `p50` と `p90` を示します。
`data.output`	`object \| null`	結果です。`status` が `succeeded` になるまでは `null` です。下の出力フィールドを参照してください。
`data.usage.credits_reserved`	`number`	タスク作成時に残高から仮確保された金額（USD）です。
`data.usage.credits_charged`	`number`	このタスクの料金（USD）です。失敗したタスクでは `0` です。
`data.usage.credits_settled`	`number`	最終的に差し引かれた金額（USD）です。タスクが成功した時点で設定され、それ以外では `0` です。
`data.usage.credits_refunded`	`number`	残高に戻された金額（USD）です。失敗したタスクでは、返金が記録された時点で仮確保した金額と一致します。
`data.usage.billable_duration_seconds`	`integer`	動画のみ。料金の算定に使われた秒数です。モデルが長さを報告しない場合は含まれません。
`data.request_id`	`string`	リクエスト ID です。サポートに問い合わせる際に添えてください。
`data.error_code`	`string \| null`	失敗コードです。タスクが失敗した場合以外は `null` です。
`data.error_message`	`string \| null`	何が問題で、何を変更すればよいかを示します。タスクが失敗した場合以外は `null` です。

完了したタスク

GET /v1/tasks/{task_id} は HTTP 200 と status: "succeeded" を返し、結果は data.output に入ります。

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "image",
    "capability_id": "gpt-image-2.6-flare-beta",
    "capability_version": 1,
    "media_type": "image",
    "model": "gpt-image-2.6-flare-beta",
    "status": "succeeded",
    "stage": "succeeded",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": {
      "media": [
        {
          "type": "image",
          "url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.png",
          "mime_type": "image/png"
        }
      ],
      "r2_url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.png"
    },
    "usage": {
      "credits_reserved": 0.022,
      "credits_settled": 0.022,
      "credits_refunded": 0,
      "credits_charged": 0.022
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

出力フィールド

フィールド	型	説明
`output.media`	`object[]`	生成されたファイルです。このモデルでは 1 件です。
`output.media[].type`	`string`	常に `image` です。
`output.media[].url`	`string`	保存された画像への HTTPS リンクです。ダウンロードして保管してください。保持期間は保証されません。
`output.media[].mime_type`	`string`	保存されたファイルの形式です。`png` では `image/png`、GIF では `image/gif` です。形式を決めつけず、この値を読み取ってください。
`output.r2_url`	`string`	1 件目の media の URL と同じ値です。古いクライアント向けです。代わりに `media` を読んでください。

失敗したタスク

失敗したタスクも、GET /v1/tasks/{task_id} では HTTP 200 になります。失敗はボディに示されます。仮確保された金額は全額戻されるため、課金されません。

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "image",
    "capability_id": "gpt-image-2.6-flare-beta",
    "capability_version": 1,
    "media_type": "image",
    "model": "gpt-image-2.6-flare-beta",
    "status": "failed",
    "stage": "failed",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": null,
    "usage": {
      "credits_reserved": 0.022,
      "credits_settled": 0,
      "credits_refunded": 0.022,
      "credits_charged": 0
    },
    "retryable": true,
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": "processing_failed",
    "error_message": "The task failed during processing on our side. Retry; a failed task is refunded."
  }
}

フィールド	型	説明
`data.error_code`	`string`	`bad_request` と `content_policy_violation`（リクエストを修正してください）、または `processing_unavailable`、`processing_timeout`、`processing_failed`、`result_transfer_failed`（時間をおいて再試行してください）のいずれかです。エラーを参照してください。
`data.error_message`	`string`	問題と対処方法を示す文です。
`data.retryable`	`boolean`	失敗したタスクにのみ含まれます。同じリクエストをもう一度送れば成功する可能性がある場合は `true` です。
`data.usage`	`object`	返金が記録された時点（通常はタスクが失敗した瞬間）で、`credits_charged` と `credits_settled` は `0` になり、`credits_refunded` は `credits_reserved` と一致します。

完全なコード例

タスクを作成し、サーバーが示すポーリング間隔で完了を待ち、結果の URL を出力します。環境変数に BEATAPI_API_KEY を設定し、requests をインストールしてください。

import os
import time
import uuid
import requests
API = "https://api.beatapi.io"
HEADERS = {"Authorization": f"Bearer {os.environ['BEATAPI_API_KEY']}"}
def create_task(body: dict) -> dict:
    # One Idempotency-Key per logical request: a retry with the same key cannot create a second task.
    headers = {**HEADERS, "Idempotency-Key": str(uuid.uuid4())}
    for attempt in range(3):
        response = requests.post(f"{API}/v1/images/tasks", headers=headers, json=body, timeout=60)
        if response.status_code in (429, 503) and attempt < 2:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        break
    try:
        payload = response.json()
    except ValueError:  # an edge error page is not JSON
        response.raise_for_status()
        raise
    if not response.ok:
        error = payload["error"]
        raise RuntimeError(f"{response.status_code} {error['code']}: {error['message']} (request_id={error.get('request_id')})")
    return payload["data"]
def wait_for_task(task_id: str, timeout_seconds: int = 1800) -> dict:
    deadline = time.monotonic() + timeout_seconds
    while time.monotonic() < deadline:
        response = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
        if response.status_code == 429 or response.status_code >= 500:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        response.raise_for_status()
        task = response.json()["data"]
        if task["status"] in ("succeeded", "failed"):
            return task
        time.sleep(task.get("poll_after_seconds", 5))
    raise TimeoutError(f"task {task_id} is still running; keep polling later")
task = create_task({
  "model": "gpt-image-2.6-flare-beta",
  "prompt": "A minimalist product photo of a glass water bottle on wet black stone, soft rim light, shallow depth of field",
  "aspect_ratio": "3:2",
  "resolution": "2K"
})
print("created", task["id"])
task = wait_for_task(task["id"])
if task["status"] == "failed":
    raise SystemExit(f"{task['error_code']}: {task['error_message']}")
for item in task["output"]["media"]:
    print(item["url"])

課金

静止画（png）は 1 タスクにつき 1 枚で、サイズ区分で課金されます。送信した resolution、または size が属する区分です（上の表）。
GIF（output_format: "gif"）は、サイズにかかわらず GIF 1 枚ごとの独自の料金で課金されます。
料金は、タスク作成時にあなたの残高から（キーにクォータがある場合はそこからも）仮確保されます。タスクが作られる前に拒否されたリクエストには課金されません。
成功したタスクでは、仮確保された金額がそのまま確定します。失敗したタスクでは全額が戻されます。

現在の定価です。料金ページと同じ金額です。割引を個別に契約しているアカウントでは、より低い金額になります。実際に課金された金額は、タスクの data.usage で確認できます。

オプション	定価（USD）
1 枚 · 1K	$0.013
1 枚 · 2K	$0.022
1 枚 · 4K	$0.03
1 枚 · GIF	$0.04

よくあるエラー

エラーまたは症状	原因	対処
400 `"size" already fixes the output; do not send "resolution" with it`	`size` を `resolution` または `aspect_ratio` と一緒に送っています（デフォルト値であっても同様です）。	`size` だけを送るか、`size` なしで `resolution` と `aspect_ratio` を送ってください。
400 `"size" width and height must be multiples of 16`	`1000x1000` や `1920x1080`（1080 は 16 の倍数ではありません）のようなサイズです。	両方の辺を 16 の倍数に丸めてください。たとえば `1920x1088` です。
400 `"size" must have between 655,360 and 8,294,400 pixels; 512x512 has 262,144`	フレームが小さすぎる、または大きすぎます。`4096x4096` は、それより前の 3840 px の辺の上限で失敗します。	辺は 3840 px 以下にし、合計ピクセル数を 655,360～8,294,400 の範囲に収めてください。
400 `"resolution" must be one of: [1K 2K 4K]`	小文字の `2k`、`8K`、または `resolution` に `2048x2048` のようなピクセルサイズを送っています。	`1K`、`2K`、`4K` のいずれかを送るか、ピクセル指定には `size` フィールドを使ってください。
400 `gpt-image-2.6-flare-beta output_format "gif" is made from the prompt alone: leave out "images"`	参照画像と一緒に GIF を要求しています。	`images` を削除してください。画像を編集して静止画にしたい場合は `output_format` を省略してください。
400 `gpt-image-2.6-flare-beta output_format "gif" has a fixed size: leave out "size"`	GIF を要求するときに、`size`、`1K` 以外の `resolution`、または `auto` 以外の `aspect_ratio` を送っています。メッセージにそのフィールド名が入ります。	`size`、`resolution`、`aspect_ratio` は省略してください。GIF のサイズはモデルが決めます。
400 `unknown field: frame_count`	GIF のフレーム指定（`frame_count` または `frame_duration_ms`）を送っています。	そのフィールドを削除してください。フレームはモデルが決めます。
400 `field "background" is not supported by model gpt-image-2.6-flare-beta`	GPT Image 2.5 のフィールド（`background`）、OpenAI API のフィールド（`quality`）、または他の画像モデルのフィールド（`seed`、`enhance_prompt`）を送っています。	そのフィールドを削除してください。
400 `unknown field: n`	1 つのタスクで複数枚の画像を要求しています。	`n` を削除し、画像 1 枚ごとにタスクを作成してください。
400 `"images[0]" must be a public HTTPS URL`	`http://` のリンク、`data:` URI、またはローカルパスを指定しています。	ファイルを HTTPS で公開するか、`POST /v1/files` でアップロードして `data.url` を使ってください。
400 `"images[1]" is not a PNG, JPEG or WebP image: the URL returned text/html`	リンク先がファイルではなく、Web ページ、ログインページ、または期限切れの署名付き URL です。	画像ファイルへ直接リンクしてください。
400 `"images[0]" could not be downloaded: the URL returned HTTP 403`	ホストがサーバーからのダウンロードをブロックしています（ホットリンク保護、またはプライベートなバケット）。	ファイルを公開するか、`POST /v1/files` でアップロードしてください。
編集した画像が正方形で返ってくる	`aspect_ratio` を省略したか `auto` を指定したため、正方形のフレームで描画されました。	希望の比率を指定するか、`size` を送ってください。
タスクが `content_policy_violation` で `failed`	プロンプト、参照画像、または生成された画像がモデレーションで拒否されました。	プロンプトまたは画像を変更してください。そのまま再試行しても再び失敗します。課金はされません。
タスクが `processing_timeout` で `failed`	画像が処理時間の上限内に完了しませんでした。	再試行してください。失敗したタスクは返金されています。

HTTP エラー早見表

タスクが作られる前のエラーは、2xx 以外のレスポンスで返されます。課金はされません。error.code または error.retryable で処理を分岐してください。message には問題の内容が示されます。全一覧と再試行のルールはエラーにあります。

{
  "error": {
    "code": "bad_request",
    "message": "\"prompt\" is required",
    "retryable": false,
    "request_id": "req_5f0c2a9e4b7d4e31"
  }
}

HTTP ステータス	`error.code`	対処方法
400	`bad_request`, `content_policy_violation`	リクエストを修正してください。メッセージにフィールド名が示されます。そのまま再試行しないでください。
401	`missing_api_key`, `invalid_api_key`（古いクライアントでは `unauthorized` が返ることがあります）	有効なキーを `Authorization: Bearer <key>` で送信してください。
402	`insufficient_credits`	残高をチャージするか、キーのクォータを引き上げてから、再度送信してください。
403	`forbidden`	このキーまたはアカウントでは、このモデルを利用できない可能性があります（たとえば、無料クレジットは一部のモデルにのみ使えます）。そのまま再試行しないでください。
404	`not_found`	`GET /v1/tasks/{task_id}` の場合：このキーのアカウントに該当するタスクが存在しません。ID を確認してください。
409	`idempotency_conflict`	新しい `Idempotency-Key` を使うか、同じキーの最初のリクエストが完了するまで待ってください。
429	`rate_limit_exceeded`	`Retry-After` の秒数（`error.retry_after_seconds` にも含まれます）だけ待ってから再試行してください。
500	`internal_error`	バックオフを入れて再試行してください。解消しない場合は、`request_id` を添えてサポートにお問い合わせください。
503	`processing_unavailable`, `processing_timeout`, `processing_failed`, `result_transfer_failed`	課金はされていません。指数バックオフで再試行してください。

認証

AuthorizationBearer

API キーを Authorization: Bearer <BEATAPI_API_KEY> として送信してください。

ヘッダー

Idempotency-Keystringオプション<=255 characters

リクエスト

This endpoint expects an object.

modelenum必須

実行するモデルです。

値：gpt-image-2.6-flare-beta

値が正しくない場合

指定がない場合："model" is required
不明なモデル ID の場合："model" gpt-image-9 is not catalogued
動画モデルをこのエンドポイントに送った場合："model" seedance-2.5 is served by POST /v1/videos/tasks, not this endpoint

許可された値:

promptstring必須1-5000 characters

長さ：1–5000 文字

長さは文字数で数えます（CJK 文字も 1 文字として数えます）。
images を送る場合は、どの画像が何の役割かを書いてください。たとえば「1 枚目の画像を商品に、2 枚目の画像を背景に使う」のように指定します。
GIF ではプロンプトが唯一の入力です。被写体と動きを書いてください。

値が正しくない場合

指定がない場合："prompt" is required
空、または上限を超える長さの場合："prompt" has an unsupported length
文字列でない場合："prompt" must be a string

aspect_ratioenumオプションデフォルト値 auto

画像の形を「幅:高さ」で指定します。resolution と一緒に送るか、両方を省略して 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

デフォルトは auto なので、このフィールドを省略したリクエストも正方形で描画されます。
2:1、1:2、3:1、1:3、21:9、9:21 といったパノラマ形状も指定できます。最も横長または縦長のフレームは 3:1 です。
size と同時には使えません。
output_format: "gif" では省略してください。GIF のフレームはモデルが決めます。その場合に受け付けるのはデフォルトの auto だけです。

備考：auto は「参照画像の形に従う」という意味ではありません。images の有無にかかわらず、選択した resolution の正方形のフレームを要求します。編集結果を別の形にしたい場合は、比率を指定するか、size を送ってください。

値が正しくない場合

一覧にない値の場合："aspect_ratio" must be one of: [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]
size と同時に送った場合："size" already fixes the output; do not send "aspect_ratio" with it
output_format: "gif" で auto 以外を送った場合：gpt-image-2.6-flare-beta output_format "gif" has a fixed size: leave out "aspect_ratio"

imageslist of stringsオプション

編集または合成する参照画像です。このフィールドを送ると、リクエストはテキストからの画像生成ではなく、画像編集として扱われます。

要素数：1–16

各要素は公開されている https:// の URL です。ローカルファイルは先にアップロード（POST /v1/files）し、返された data.url を渡してください。

各リンクは、公開 HTTPS で画像ファイルそのもの（PNG、JPEG、WebP）を返し、サイズが 50 MB 以下である必要があります。ゲートウェイは、タスクを作成する前に、すべてのリンクの先頭バイトをダウンロードし、ファイル名や Content-Type ではなく、そのバイト列から形式を判定します。
Web ページ、ログインが必要なページ、期限切れの署名付き URL、ホットリンク保護のあるホストへのリンクは、画像を返さないため拒否されます。
エラーメッセージ中の位置は 0 始まりです。images[0] は 1 番目のリンクを指します。
output_format: "gif" とは同時に使えません。GIF はプロンプトだけから作られます。

値が正しくない場合

最大数を超えた場合："images" accepts at most 16 items
空の配列の場合："images" requires at least 1 item
https:// のリンクでない場合："images[0]" must be a public HTTPS URL
プライベートまたは安全でないアドレスの場合："images[0]" must be a publicly reachable HTTPS image URL
ホストが 4xx エラーを返した場合："images[0]" could not be downloaded: the URL returned HTTP 404
リンクが PNG、JPEG、WebP 以外を返した場合："images[0]" is not a PNG, JPEG or WebP image: the URL returned text/html
50 MB を超える場合："images[2]" is 63.4 MB; images must be 50 MB or smaller
output_format: "gif" と同時に送った場合：gpt-image-2.6-flare-beta output_format "gif" is made from the prompt alone: leave out "images"

例

"images": [
  "https://cdn.beatapi.io/samples/smart-bottle.png",
  "https://cdn.beatapi.io/samples/neon-singer.png"
]

output_formatenumオプションデフォルト値 png

作成するファイルの種類です。png は静止画、gif は短いアニメーションです。

指定できる値：png, gif

デフォルト：png

png（デフォルト）は、指定した resolution、aspect_ratio、size で静止画を生成し、サイズ区分ごとに課金されます。
gif は短いアニメーションを作ります。サイズ（約 300～1024 px）とフレーム数はモデルが決めます。size、resolution、aspect_ratio は一緒に送らないでください。
GIF はプロンプトだけから作られます。images は使えず、frame_count と frame_duration_ms にも対応していません。
GIF はサイズにかかわらず、GIF 1 枚ごとの独自の料金で課金されます。料金表をご覧ください。
このページでは、アニメーションがループ再生されることは保証しません。

値が正しくない場合

一覧にない値の場合："output_format" must be one of: [png gif]
gif と images を同時に送った場合：gpt-image-2.6-flare-beta output_format "gif" is made from the prompt alone: leave out "images"
gif と size を同時に送った場合：gpt-image-2.6-flare-beta output_format "gif" has a fixed size: leave out "size"

例

"output_format": "gif"

許可された値:

resolutionenumオプションデフォルト値 1K

指定できる値：1K, 2K, 4K

デフォルト：1K

大文字の K を使ってください。2k は拒否されます。
このページでは、区分ごとの正確なピクセル寸法は保証しません。正確なフレームが必要な場合は size を送ってください。
size と同時には使えません。size は独自のサイズを持ち、ピクセル数に応じて課金されます。
output_format: "gif" では省略してください。GIF には独自のサイズと料金があります。その場合に受け付けるのはデフォルトの 1K だけです。

値が正しくない場合

一覧にない値の場合："resolution" must be one of: [1K 2K 4K]
size と同時に送った場合："size" already fixes the output; do not send "resolution" with it
output_format: "gif" で 1K 以外を送った場合：gpt-image-2.6-flare-beta output_format "gif" has a fixed size: leave out "resolution"

許可された値:

sizestringオプション形式: "image-size"

ピクセル単位の正確な出力サイズを WIDTHxHEIGHT の形式で指定します。例：1536x1024。resolution と aspect_ratio の代わりになります。

両方の辺が 16 の倍数で、16～3840 px の範囲内である必要があります。
合計ピクセル数は 655,360～8,294,400 の範囲内で、長辺は短辺の 3 倍以下にしてください。
区切り文字には x、X、× を使えます。前後のスペースは無視されます。
価格区分はピクセル数で決まります。2,097,152 ピクセル以下は 1K、5,898,240 以下は 2K、それを超えると 4K です。例は下の表「size の課金方法」をご覧ください。
resolution や aspect_ratio は、デフォルト値であっても一緒に送らないでください。
output_format: "gif" とは同時に使えません。

備考：size は送信した値のとおりに検証・課金されますが、納品される画像のピクセル数がその値と完全に一致することは、このページでは保証しません。正確な寸法がパイプラインに必要な場合は、保存されたファイルを読み取ってください。

値が正しくない場合

文字列でない場合："size" must be a string
WIDTHxHEIGHT の形式でない場合（数字だけ、auto、カンマなど）："size" must be WIDTHxHEIGHT in pixels, for example 1536x1024
辺が 16 の倍数でない場合："size" width and height must be multiples of 16
辺が 16 未満または 3840 を超える場合："size" edges must be between 16 and 3840 pixels
ピクセル数が少なすぎる、または多すぎる場合："size" must have between 655,360 and 8,294,400 pixels; 512x512 has 262,144
3:1 より横長または縦長の場合："size" must not be wider or taller than 3:1
resolution と同時に送った場合："size" already fixes the output; do not send "resolution" with it
aspect_ratio と同時に送った場合："size" already fixes the output; do not send "aspect_ratio" with it
output_format: "gif" と同時に送った場合：gpt-image-2.6-flare-beta output_format "gif" has a fixed size: leave out "size"

例

"size": "1536x1024"

レスポンス

エラー

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

403

Forbidden Error

409

Conflict Error

429

Too Many Requests Error

500

Internal Server Error

503

Service Unavailable Error

モデル ID

エンドポイントと認証

Authorization string 必須

リクエストの流れ

タスクを作成する

完了を待つ

結果を保存する

入力モード

リクエストパラメーター

model string 必須

prompt string 必須

images string[] 任意

aspect_ratio string 任意デフォルト: auto

resolution string 任意デフォルト: 1K

size string 任意

output_format string 任意デフォルト: png

入力メディアの上限

フレームの選び方：resolution と aspect_ratio、または size

GIF アニメーションを作る

このモデルが受け付けないフィールド

size の課金方法

リクエスト例

テキストから画像

1 枚の画像を編集

複数の画像を合成

正確なサイズ

GIF アニメーション

レスポンス

タスクの作成（201）

完了したタスク

出力フィールド

失敗したタスク

完全なコード例

課金

よくあるエラー

HTTP エラー早見表

認証

ヘッダー

リクエスト

レスポンス

エラー

`Authorization` string 必須

`model` string 必須

`prompt` string 必須

`images` string[] 任意

`aspect_ratio` string 任意デフォルト: `auto`

`resolution` string 任意デフォルト: `1K`

`size` string 任意

`output_format` string 任意デフォルト: `png`

フレームの選び方：`resolution` と `aspect_ratio`、または `size`

`size` の課金方法