> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# 価格比較 API

> API キーなしで、BeatAPI のモデル規格の価格を他のプラットフォームが同じ規格に公開している価格と比較します。

# 価格比較 API

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

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

## クイックスタート

```bash
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` は時間とともに変わるため、最新の値は実際に呼び出して確認してください。

```bash
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"]}'
```

```json
{
  "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` を返します。

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

```json
{
  "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` は含まれません。

## エラー

エラーは共通の[エラーオブジェクト](/errors)で返ります。修正が必要なリクエストは `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` を添えてサポートに連絡してください。