> 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 가격을 다른 플랫폼이 같은 규격에 공개한 가격과 비교합니다. 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 하나입니다. 대소문자를 구분하지 않으며 점과 하이픈은 같은 것으로 취급합니다. |
| `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` 값은 시간이 지나면 바뀌므로 최신 수치는 엔드포인트를 직접 호출해 확인하세요.

```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`). 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`을 반환합니다.

```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`                                                                                      |
| --------------------------- | ---------------------------------------------------------------------------------------------- |
| 요청 본문이 올바른 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`를 첨부해 지원팀에 문의하세요.