가격 비교 API

POST /v1/price-comparisons는 공개된 요금 규격 하나에 대해 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 하나입니다. 대소문자를 구분하지 않으며 점과 하이픈은 같은 것으로 취급합니다.
`spec`	string	아니요	`GET /v1/pricing`에 있는 해당 모델의 규격 ID 하나입니다(예: `nano-banana-pro-4k`). 생략하면 기본 구성을 비교합니다.
`providers`	string[]	아니요	비교할 플랫폼 ID이며 최대 20개입니다. 생략하면 해당 규격의 가격이 저장된 모든 플랫폼이 참여하며 BeatAPI도 포함됩니다.

model과 spec은 각각 최대 200자입니다. model이 비어 있으면 spec으로 모델을 찾습니다.

기본 구성

spec이 없으면 어느 플랫폼이 이기는지가 아니라 규격의 형태로만 구성 하나를 고릅니다.

텍스트 모델: 입력 토큰.
영상 모델: 참조 영상이나 영상-영상 입력이 없는 첫 번째 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). 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`	플랫폼마다 한 항목이며, `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`	규격 이름에 적힌 길이의 영상 한 편 전체이며, 1초당 가격이 아닙니다.
`1M_tokens`	해당 규격의 토큰 100만 개(예: 입력 토큰).

모든 금액은 USD이며 10진수 문자열로 반환되므로 작은 가격이 0으로 반올림되지 않습니다. 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일 안에 확인했으며, 규격과 정확히 일치하고, 추정가가 아닌 가격만 순위에 들어갑니다. 그 밖의 가격도 exclusion_reason과 함께 quotes에 남으므로 누가 왜 빠졌는지 확인할 수 있습니다.

BeatAPI 가격은 GET /v1/pricing의 실시간 소매가이므로 BeatAPI 가격이 바뀌면 다음 비교에 바로 반영됩니다. 다른 플랫폼의 가격은 각 플랫폼의 공개 페이지와 대조해 수작업으로 확인합니다.

요약과 네 가지 지표

필드	설명
`winner_providers` / `lowest_amount`	순위에 든 최저가와 그 가격의 모든 플랫폼입니다. 동률이면 모두 나열합니다.
`benchmarks.lowest_below_second_percentage`	최저가가 2위 가격보다 얼마나 낮은지입니다. 동률도 순위에 포함하므로 최저가가 동률이면 `"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`	결과를 설명하는 영어 문장 하나.

백분율은 소수점 둘째 자리까지의 문자열이며, 반올림하지 않은 금액으로 계산한 뒤 마지막에 반올림합니다. 순위에 든 플랫폼이 둘 미만이거나 분모가 0이면 해당 지표는 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`
요청 본문이 올바른 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를 첨부해 지원팀에 문의하세요.