価格比較 API

POST /v1/price-comparisons は、BeatAPI が公開している料金規格 1 つについて、BeatAPI の価格と、他のプラットフォームが同じ規格に公開している価格を比較します。API キーは不要で、課金もされません。

この比較は中立です。BeatAPI も他のプラットフォームと同じルールで順位付けされ、他のプラットフォームのほうが安い場合はそのまま返します。このとき beatapi_position は not_lowest です。

クイックスタート

curl https://api.beatapi.io/v1/price-comparisons \
  -H "Content-Type: application/json" \
  -d '{"model":"Nano Banana Pro"}'

model だけを指定すると、そのモデルの標準的な規格を、その規格の価格が登録されているすべてのプラットフォームと比較します。別の規格を選ぶには spec を、比較するプラットフォームを選ぶには providers を指定します。

リクエスト

フィールド	型	必須	説明
`model`	string	はい（`spec` を指定する場合は省略可）	モデルの表示名（`Nano Banana Pro`）、ページの slug、規格 ID の共通プレフィックス、または規格 ID 1 つ。大文字と小文字は区別せず、ドットとハイフンは同じものとして扱います。
`spec`	string	いいえ	`GET /v1/pricing` にあるそのモデルの規格 ID 1 つ。例：`nano-banana-pro-4k`。省略すると標準的な規格を比較します。
`providers`	string[]	いいえ	比較するプラットフォーム ID。最大 20 個。省略すると、その規格の価格が登録されているすべてのプラットフォームが対象になり、BeatAPI も含まれます。

model と spec はそれぞれ最大 200 文字です。model が空の場合は、spec からモデルを探します。

標準的な規格

spec を省略した場合は、規格の形だけで 1 つを選びます。どのプラットフォームが安いかでは選びません。

テキストモデル：入力トークン。
動画モデル：参照動画なし、かつ動画から動画への変換ではない最初の 720p 規格。
画像モデル：最初の通常の画像規格。例：nano-banana-pro-1k。

model 自体が規格 ID の場合は、その規格を比較します。

規格 ID

規格 ID は匿名で読める料金表から取得できます。GET https://api.beatapi.io/v1/pricing の data.groups[].specs[] の各項目に id があります。比較結果にも、そのモデルの available_specs が含まれます。

プラットフォーム ID

プラットフォーム ID は小文字で、quotes[].provider に返る値と同じです。beatapi は BeatAPI を表します。providers を指定すると、列挙したプラットフォームだけを比較します。BeatAPI を順位付けに含めるには beatapi も列挙してください。列挙したプラットフォームにその規格の価格がない場合は、pending_verification として返ります。比較表にない ID は 400 で拒否されます。

レスポンス

成功すると 200 を返し、結果は data に入ります。外側の構造は GET /v1/pricing と同じです。レスポンスはキャッシュされません（Cache-Control: no-store）。

次の例は 2026-11-11 に確認した価格を使っています。価格、日付、data_version は時間とともに変わるため、最新の値は実際に呼び出して確認してください。

curl https://api.beatapi.io/v1/price-comparisons \
  -H "Content-Type: application/json" \
  -d '{"model":"Nano Banana Pro","spec":"nano-banana-pro-1k","providers":["beatapi","atlascloud","fal","google","higgsfield","wavespeed"]}'

{
  "data": {
    "status": "ready",
    "model": "Nano Banana Pro",
    "spec": {
      "id": "nano-banana-pro-1k",
      "label": "1 image · 1K",
      "label_zh": "1 张图片 · 1K",
      "category": "image",
      "unit": "image"
    },
    "available_specs": ["nano-banana-pro-1k", "nano-banana-pro-2k", "nano-banana-pro-4k"],
    "questions": [],
    "quotes": [
      {
        "provider": "beatapi",
        "status": "quoted",
        "provider_model_id": "Nano Banana Pro",
        "amount": "0.05",
        "currency": "USD",
        "quote_kind": "fixed",
        "matched_configuration": "1 image · 1K",
        "source_urls": ["https://api.beatapi.io/v1/pricing", "https://beatapi.io/nano-banana-pro-api"],
        "checked_at": "2026-11-11T10:00:00Z",
        "expires_at": null,
        "freshness_status": "fresh",
        "rank_eligible": true,
        "exclusion_reason": null
      },
      {
        "provider": "atlascloud",
        "status": "quoted",
        "provider_model_id": "google/nano-banana-pro/text-to-image",
        "amount": "0.14",
        "currency": "USD",
        "quote_kind": "estimate",
        "matched_configuration": "1k · 1:1 · 1 张 · 文生图 · 不开 web/image search · thinking 默认",
        "source_urls": ["https://www.atlascloud.ai/models/google/nano-banana-pro/text-to-image"],
        "checked_at": "2026-11-11T08:59:27Z",
        "expires_at": "2026-12-11T08:59:27Z",
        "freshness_status": "fresh",
        "rank_eligible": false,
        "exclusion_reason": "Estimated by the provider's calculator, not a fixed price."
      },
      {
        "provider": "fal",
        "status": "quoted",
        "provider_model_id": "fal-ai/nano-banana-pro",
        "amount": "0.15",
        "currency": "USD",
        "quote_kind": "fixed",
        "matched_configuration": "Nano Banana Pro text-to-image resolution=1K, no web search",
        "source_urls": ["https://fal.ai/models/fal-ai/nano-banana-pro"],
        "checked_at": "2026-11-11T08:50:26Z",
        "expires_at": "2026-12-11T08:50:26Z",
        "freshness_status": "fresh",
        "rank_eligible": true,
        "exclusion_reason": null
      },
      {
        "provider": "google",
        "status": "quoted",
        "provider_model_id": "gemini-3-pro-image",
        "amount": "0.1344",
        "currency": "USD",
        "quote_kind": "formula",
        "matched_configuration": "gemini-3-pro-image text-to-image 1K 1:1, Standard paid tier, 1 output image",
        "source_urls": ["https://ai.google.dev/gemini-api/docs/pricing#gemini-3-pro-image"],
        "checked_at": "2026-11-11T08:50:17Z",
        "expires_at": "2026-12-11T08:50:17Z",
        "freshness_status": "fresh",
        "rank_eligible": true,
        "exclusion_reason": null
      },
      {
        "provider": "higgsfield",
        "status": "unsupported_configuration",
        "amount": null,
        "currency": "USD",
        "source_urls": ["https://open.higgsfield.ai/pricing"],
        "checked_at": "2026-11-11T08:48:09Z",
        "expires_at": "2026-12-11T08:48:09Z",
        "freshness_status": "fresh",
        "rank_eligible": false,
        "exclusion_reason": "The provider does not offer this model or configuration."
      },
      {
        "provider": "wavespeed",
        "status": "quoted",
        "provider_model_id": "google/nano-banana-pro/text-to-image",
        "amount": "0.126",
        "currency": "USD",
        "quote_kind": "fixed",
        "matched_configuration": "1k · 1:1 · 1 张 · 文生图 · 不开 web/image search",
        "source_urls": ["https://wavespeed.ai/models/google/nano-banana-pro/text-to-image"],
        "checked_at": "2026-11-11T08:52:36Z",
        "expires_at": "2026-12-11T08:52:36Z",
        "freshness_status": "fresh",
        "rank_eligible": true,
        "exclusion_reason": null
      }
    ],
    "summary": {
      "winner_providers": ["beatapi"],
      "lowest_amount": "0.05",
      "ranking_scope": ["beatapi", "wavespeed", "google", "fal"],
      "excluded_providers": ["atlascloud", "higgsfield"],
      "coverage_complete": true,
      "beatapi_position": "lowest",
      "conclusion": "beatapi has the lowest price of 4 verified providers at $0.05.",
      "benchmarks": {
        "provider_count": 4,
        "mean_scope": ["beatapi", "wavespeed", "google", "fal"],
        "mean_amount": "0.1151",
        "second_provider_amount": "0.126",
        "second_provider_providers": ["wavespeed"],
        "lowest_below_second_percentage": "60.32",
        "lowest_below_mean_percentage": "56.56"
      }
    },
    "data_version": "quotes-684-1794391200",
    "generated_at": "2026-11-11T10:00:00Z"
  }
}

この例の数値は、次のように価格から求められます。

順位付けに使われる価格は 0.05、0.126、0.1344、0.15 の 4 つです。atlascloud の見積もりと、higgsfield が提供していない規格は一覧に残りますが、順位付けには使われません。
最安値：0.05（beatapi）。2 位：0.126（wavespeed）。(0.126 − 0.05) ÷ 0.126 = 60.32%。
平均：(0.05 + 0.126 + 0.1344 + 0.15) ÷ 4 = 0.1151。(0.1151 − 0.05) ÷ 0.1151 = 56.56%。

トップレベルのフィールド

フィールド	説明
`status`	`needs_clarification`、`ready`、`partial`、`unavailable` のいずれか（下表を参照）。
`model`	比較したモデル。料金表と同じ名前です。
`model_candidates`	`needs_clarification` のときだけ返ります。`model` として送り直せるモデルで、最大 10 個です。
`spec`	比較した対象：`id`、`label`、`label_zh`、`category`、`unit`。`needs_clarification` のときは `null` です。
`available_specs`	そのモデルのすべての規格 ID。`spec` を指定して再度呼び出すときに使えます。
`questions`	リクエストがあいまいなときに、次に送るべき内容を示します。それ以外は空配列です。
`quotes`	プラットフォームごとに 1 項目。`beatapi` が先頭で、残りは ID 順です。
`summary`	順位と 4 つの指標。`needs_clarification` のときは `null` です。
`data_version`	登録済みの価格が変わるたびに変わります。呼び出し間の比較に使い、内容は解析しないでください。
`generated_at`	結果を計算した時刻（UTC）。

`status`	意味
`needs_clarification`	モデルを特定できないか、複数のモデルが一致しました。`quotes` は空で、`summary` は `null` です。`model_candidates` から 1 つ選んで送り直してください。
`ready`	列挙したすべてのプラットフォームについて、その規格の結論が出ています。
`partial`	少なくとも 1 つの価格が `pending_verification`、`source_conflict`、`stale`、`incomplete_price` のいずれかです。順位付けは、順位付けできる価格だけで行います。
`unavailable`	比較できる内容がありません。順位のない結果として扱ってください。

単位

`spec.unit`	すべての金額が表す価格
`image`	その規格の画像 1 枚。
`video`	規格名に書かれた長さの動画 1 本。1 秒あたりではありません。
`1M_tokens`	その規格の 100 万トークン。例：入力トークン。

金額はすべて米ドルで、10 進数の文字列として返るため、少額の価格がゼロに丸められることはありません。null は信頼できる価格がないことを表し、無料は "0" で表します。

価格

フィールド	説明
`provider`	プラットフォーム ID。
`status`	`quoted`、`stale`、`incomplete_price`、`unsupported_configuration`、`no_public_price`、`source_conflict`、`pending_verification` のいずれか。
`provider_model_id`	そのプラットフォーム自身のモデル名またはエンドポイント名（分かる場合）。
`amount`	1 単位あたりの価格、または `null`。
`quote_kind`	`fixed`（掲載価格）、`formula`（公開レートからの計算）、`estimate`（計算ツールの見積もり）。
`matched_configuration`	価格を読み取った構成。確認時の表記のまま返します。
`note`	任意の補足。例：BeatAPI の価格にかかる時間帯別の倍率。
`source_urls`	価格を読み取った公開ページ。
`checked_at` / `expires_at`	価格を確認した時刻と、順位付けに使われなくなる時刻（30 日後）。BeatAPI の価格はリアルタイムで読み取るため、`checked_at` は呼び出し時刻で、`expires_at` は `null` です。
`freshness_status`	`fresh`、`stale`、`unknown` のいずれか。
`rank_eligible`	その価格が順位付けに使われるかどうか。
`exclusion_reason`	一覧に残るものの順位付けに使われない理由。順位付けに使われる場合は `null` です。

順位付けに使われるのは、金額があり、30 日以内に確認され、規格と完全に一致し、見積もりではない価格だけです。それ以外の価格も exclusion_reason 付きで quotes に残るため、どのプラットフォームがなぜ除外されたかを確認できます。

BeatAPI の価格は GET /v1/pricing のリアルタイムの小売価格です。BeatAPI の価格が変わると、次の比較から反映されます。他のプラットフォームの価格は、各社の公開ページと照らし合わせて手作業で確認しています。

サマリーと 4 つの指標

フィールド	説明
`winner_providers` / `lowest_amount`	順位付けされた最安値と、その価格のすべてのプラットフォーム。同額の場合はすべて列挙します。
`benchmarks.lowest_below_second_percentage`	最安値が 2 位の価格よりどれだけ低いか。同額も順位に数えるため、最安値が同額で並ぶと `"0.00"` になります。`second_provider_amount` と `second_provider_providers` が 2 位の価格とプラットフォームを示します。
`benchmarks.mean_amount`	順位付けされたすべての価格の平均。BeatAPI を含み、1 プラットフォームにつき 1 つの価格です（`mean_scope`）。
`benchmarks.lowest_below_mean_percentage`	最安値が平均よりどれだけ低いか。
`benchmarks.provider_count`	順位付けされたプラットフォームの数。
`ranking_scope` / `excluded_providers`	順位付けされたプラットフォーム（安い順）と、列挙されたものの順位付けされなかったプラットフォーム。
`coverage_complete`	結果が `partial` のときは `false` です。
`beatapi_position`	`lowest`、`tied_lowest`、`not_lowest`、`insufficient_comparison`、`not_compared` のいずれか。
`conclusion`	結果を述べる英語の 1 文。

パーセンテージは小数点以下 2 桁の文字列で、丸める前の金額から計算し、最後に四捨五入します。順位付けされたプラットフォームが 2 つ未満の場合や分母がゼロの場合、その指標は null になり、NaN にはなりません。mean_amount は小数点以下 8 桁に丸めます。

`beatapi_position`	意味
`lowest`	BeatAPI だけが順位付けされた最安値です。
`tied_lowest`	BeatAPI が他の 1 つ以上のプラットフォームと同額で最安値です。
`not_lowest`	他のプラットフォームのほうが安いです。
`insufficient_comparison`	BeatAPI は順位付けされましたが、他に順位付けされたプラットフォームがないため比較できません。
`not_compared`	BeatAPI が順位付けされていません。例：`providers` に `beatapi` を含めなかった場合。

モデルがあいまいな場合

名前が複数のモデルに一致すると、200 と needs_clarification を返します。

curl https://api.beatapi.io/v1/price-comparisons \
  -H "Content-Type: application/json" \
  -d '{"model":"banana pro"}'

{
  "data": {
    "status": "needs_clarification",
    "model_candidates": ["Nano Banana Pro", "Nano Banana Pro Standard"],
    "spec": null,
    "questions": ["Which model do you want to compare? Send one of model_candidates as model."],
    "quotes": [],
    "summary": null,
    "data_version": "quotes-684-1794391200",
    "generated_at": "2026-11-11T10:00:00Z"
  }
}

候補から 1 つをそのまま model として送ってください。名前、slug、規格 ID の完全一致は部分一致より常に優先されるため、Nano Banana Pro は 1 つのモデルに決まります。どのモデルにも一致しない名前でも needs_clarification を返しますが、model_candidates は含まれません。

エラー

エラーは共通のエラーオブジェクトで返ります。修正が必要なリクエストは 400 bad_request を返し、message が問題を示します。

原因	`message`
リクエストボディが有効な JSON ではない	`Invalid price comparison request.`
`spec` がそのモデルの規格ではない	`spec "nano-banana-2-1k" is not a spec of Nano Banana Pro; see GET /v1/pricing for its specs.`
`providers` に不明なプラットフォームがある	`unknown provider "example".`
同じプラットフォームを 2 回列挙した	`provider "fal" is listed twice.`
`model` または `spec` が長すぎる	`model and spec must be at most 200 characters.`
プラットフォームが 20 個を超える	`providers may list at most 20 entries.`

400 はそのまま再送しないでください。500 internal_error は比較を計算できなかったことを表します。1 回だけ再試行し、それでも失敗する場合は request_id を添えてサポートに連絡してください。