> 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 key，把 BeatAPI 某个型号规格的价格与其他平台同一规格的公开价放在一起比较。

# 比价 API

`POST /v1/price-comparisons` 把 BeatAPI 某个已公开计价规格的价格，与其他平台对同一规格公开标出的价格放在一起比较。调用不需要 API key，也不计费。

这是中立比价。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。匹配不区分大小写，点号和短横线视为相同。 |
| `spec`      | string    |                否 | 该型号在 `GET /v1/pricing` 里的一个规格 ID，例如 `nano-banana-pro-4k`。不传时比较常用规格。       |
| `providers` | string\[] |                否 | 参与比较的平台 ID，最多 20 个。不传时，所有存有该规格报价的平台都参与，包括 BeatAPI。                        |

`model` 和 `spec` 各自最长 200 个字符。`model` 为空时，用 `spec` 查找型号。

### 常用规格

不传 `spec` 时，按规格形态选出一个规格，与哪个平台更便宜无关：

* 文本型号：输入 tokens。
* 视频型号：第一个不带参考视频、也不是视频转视频的 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。`atlascloud` 的估价和 `higgsfield` 不提供的规格照列，但不参与排名。
* 最低价：0.05（`beatapi`）。第二位：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`           | 每个平台一项，`beatapi` 在最前，其余按 ID 排序。                                                    |
| `summary`          | 排名与四项指标。`needs_clarification` 时为 `null`。                                           |
| `data_version`     | 存储的报价一有变化就会改变。可在两次调用之间比较，不要解析其内容。                                                  |
| `generated_at`     | 结果的计算时间（UTC）。                                                                      |

| `status`              | 含义                                                                                             |
| --------------------- | ---------------------------------------------------------------------------------------------- |
| `needs_clarification` | 没认出型号，或有多个型号匹配。`quotes` 为空，`summary` 为 `null`；请从 `model_candidates` 中选一个重新提交。                  |
| `ready`               | 列出的每个平台对该规格都有确定结论。                                                                             |
| `partial`             | 至少有一个报价是 `pending_verification`、`source_conflict`、`stale` 或 `incomplete_price`。排名只覆盖可以参与排名的报价。 |
| `unavailable`         | 没有可比较的内容。按没有排名的结果处理。                                                                           |

### 计价单位

| `spec.unit` | 所有金额都是以下单位的价格               |
| ----------- | --------------------------- |
| `image`     | 该规格的一张图片。                   |
| `video`     | 规格名称里写明时长的一整条视频，不是每秒。       |
| `1M_tokens` | 该规格的一百万 tokens，例如输入 tokens。 |

所有金额以美元计，并以十进制字符串返回，小额价格不会被舍入成零。`null` 表示没有可信的价格；`"0"` 才表示免费。

### 报价

| 字段                          | 说明                                                                                                                            |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `provider`                  | 平台 ID。                                                                                                                        |
| `status`                    | `quoted`、`stale`、`incomplete_price`、`unsupported_configuration`、`no_public_price`、`source_conflict` 或 `pending_verification`。 |
| `provider_model_id`         | 该平台自己的型号或端点名称（已知时返回）。                                                                                                         |
| `amount`                    | 一个计价单位的完整价格，或 `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 天内核对过、与该规格完全一致、不是估价。其他报价仍保留在 `quotes` 中并附 `exclusion_reason`，可以看到谁没参与、为什么。

BeatAPI 的报价是 `GET /v1/pricing` 里的实时零售价，BeatAPI 一改价，下一次比价就会体现。其他平台的价格由人工对照其公开页面核对。

### 汇总与四项指标

| 字段                                          | 说明                                                                                                     |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `winner_providers` / `lowest_amount`        | 参与排名的最低价，以及报这个价的全部平台。并列时全部列出。                                                                          |
| `benchmarks.lowest_below_second_percentage` | 最低价比第二位低多少。并列也计入，所以并列最低时为 `"0.00"`。`second_provider_amount` 和 `second_provider_providers` 给出第二位的价格和平台。 |
| `benchmarks.mean_amount`                    | 所有参与排名价格的均价，包括 BeatAPI，每个平台一个价格（`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`                                | 一句英文结论。                                                                                                |

百分比是保留两位小数的字符串，用未舍入的金额计算，最后四舍五入。参与排名的平台不足两家或分母为零时，该指标为 `null`，不会出现 `NaN`。`mean_amount` 保留 8 位小数。

| `beatapi_position`        | 含义                                            |
| ------------------------- | --------------------------------------------- |
| `lowest`                  | 只有 BeatAPI 是参与排名的最低价。                         |
| `tied_lowest`             | BeatAPI 与至少一个其他平台并列最低。                        |
| `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"
  }
}
```

从候选中选一个原样作为 `model` 提交。完整名称、slug 或规格 ID 的精确匹配总是优先于部分匹配，所以 `Nano Banana Pro` 只会对应一个型号。名称一个型号都匹配不上时，同样返回 `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".`                                                                  |
| 同一平台列了两次            | `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` 表示比价暂时无法计算；重试一次，仍失败请带上 `request_id` 联系支持。