比价 API

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

这是中立比价。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。匹配不区分大小写，点号和短横线视为相同。
`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 都会随时间变化，以实际调用结果为准。

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。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：

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"
  }
}

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