> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toapis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 가격 및 실제 청구 금액

> API Key에서 사용할 수 있는 가격과 생성 응답의 확정 청구 금액을 조회합니다

<Note>
  중국 본토에서는 Base URL로 `https://toapis.cn`을 사용하세요. 아래 예시의 `https://toapis.com`을 `https://toapis.cn`으로 바꾸면 됩니다.
</Note>

`GET /v1/pricing`은 현재 API Key에서 사용할 수 있는 이미지 및 동영상 모델의 요금을 반환합니다. 고객별 고정 가격 또는 할인과 적용되는 그룹 가격이 이미 반영되어 있습니다.

이 엔드포인트는 요금 카탈로그를 반환합니다. 개별 생성 요청의 견적이 아니며 가격을 예약하거나 고정하지 않고, 생성 파라미터로 총비용을 계산하지 않습니다.

## 인증

<ParamField header="Authorization" type="string" required>
  생성 API Key를 `Bearer YOUR_API_KEY` 형식으로 전송합니다.
</ParamField>

## 쿼리 파라미터

<ParamField query="model" type="string">
  정확한 모델 ID입니다. 생략하면 사용 가능한 모든 이미지 및 동영상 모델을 반환합니다.
</ParamField>

<ParamField query="type" type="string">
  `image` 또는 `video`로 필터링합니다.
</ParamField>

<ParamField query="limit" type="integer" default="100">
  반환할 모델 수입니다. `1`부터 `100`까지 지정할 수 있습니다.
</ParamField>

<ParamField query="after" type="string">
  이전 응답의 `next_after`를 페이지네이션 커서로 사용합니다.
</ParamField>

Seedance 지역별 버전은 서로 다른 모델 ID를 사용합니다. 예를 들어 `model`에 `seedance-2-5`, `seedance-2-5-cn`, `seedance-2-5-global`을 지정합니다. 별도의 지역 쿼리 파라미터는 없습니다.

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://toapis.com/v1/pricing?model=seedance-2-5' \
    --header 'Authorization: Bearer <token>'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "object": "list",
    "currency": "USD",
    "data": [
      {
        "id": "seedance-2-5",
        "type": "video",
        "prices": [
          {
            "group": "default",
            "conditions": {"resolution": "720p", "has_video_input": false},
            "charge_type": "per_token",
            "price_basis": "total_tokens",
            "unit": "1m_tokens",
            "unit_price": "4"
          }
        ]
      }
    ],
    "has_more": false,
    "next_after": ""
  }
  ```
</ResponseExample>

위 금액은 응답 형식을 설명하기 위한 예시입니다. 현재 API Key에 실제로 반환된 가격을 사용하세요.

## 가격 필드

<ResponseField name="currency" type="string">
  가격 통화입니다. 현재 `USD`입니다.
</ResponseField>

<ResponseField name="object" type="string">
  객체 유형입니다. 항상 `list`입니다.
</ResponseField>

<ResponseField name="data" type="array">
  사용 가능한 모델 목록입니다. 각 항목에는 정확한 모델 `id`, `type`, 0개 이상의 `prices`가 포함됩니다.
</ResponseField>

<ResponseField name="has_more" type="boolean">
  다음 페이지가 있는지 나타냅니다.
</ResponseField>

<ResponseField name="next_after" type="string">
  다음 요청에 사용할 커서입니다. `has_more`가 `false`이면 빈 문자열입니다.
</ResponseField>

<ResponseField name="prices[].group" type="string">
  가격이 적용되는 라우팅 그룹입니다. API Key가 자동 그룹 선택을 사용하면 여러 그룹이 반환될 수 있습니다.
</ResponseField>

<ResponseField name="prices[].conditions" type="object">
  가격이 적용되는 조건입니다. 가격에 영향을 주는 모델 기본값도 포함됩니다. 생성 요청을 이 값에 맞추세요.
</ResponseField>

<ResponseField name="prices[].charge_type" type="string">
  `per_request`, `per_second`, `per_token` 중 하나입니다.
</ResponseField>

<ResponseField name="prices[].price_basis" type="string">
  청구 기준입니다. `request`, `output_seconds`, `total_tokens`, `text_input_tokens` 중 하나입니다.
</ResponseField>

<ResponseField name="prices[].unit" type="string">
  가격 단위입니다. `request`, `second`, `1m_tokens` 중 하나입니다.
</ResponseField>

<ResponseField name="prices[].unit_price" type="string">
  USD 기준 적용 단가를 10진수 문자열로 반환합니다. 고객 가격과 그룹 배율이 이미 반영되어 있으므로 그룹 배율을 다시 곱하지 마세요.
</ResponseField>

가격에는 `input_unit_price`, `input_image_unit_price`, `free_input_image_count`, `minimum_charge_usd`, `image_token_prices`가 포함될 수 있습니다. 시간대별 가격에는 `pricing_period`, `pricing_timezone`, `pricing_schedule_version`, `pricing_peak_windows`가 포함될 수 있습니다.

이미지 토큰 가격의 `image_token_prices`에는 `text_input`, `cached_text_input`, `image_input`, `cached_image_input`, `image_output`이 포함될 수 있습니다. 각 금액의 단위는 100만 토큰당 USD입니다.

표시된 조건과 호환되는 활성 후보 채널이 하나 이상 있는 가격만 반환합니다. 이 확인은 경로를 예약하거나 채널의 실시간 상태를 검사하지 않습니다. 안전하게 전체 가격을 공개할 수 없으면 모델이 반환되더라도 `prices`가 비어 있을 수 있습니다. 빈 배열이나 가격 항목 누락은 무료라는 뜻이 아닙니다.

## 실제 청구 금액

청구 금액을 확인할 수 있으면 생성 응답에 다음 객체가 포함됩니다.

```json theme={null}
{
  "billing": {
    "status": "settled",
    "credits": "100",
    "cost_usd": "0.5"
  }
}
```

| 필드         | 의미                                    |
| ---------- | ------------------------------------- |
| `status`   | `pending`, `settled`, `refunded` 중 하나 |
| `credits`  | 확정된 ToAPIs Credits 사용량이며 10진수 문자열로 반환 |
| `cost_usd` | 같은 확정 청구의 USD 금액이며 10진수 문자열로 반환       |

`pending`은 최종 금액이 아직 확정되지 않았음을 뜻하며 금액 필드는 생략됩니다. `refunded`는 확정된 순 청구 금액이 0임을 뜻합니다. `billing` 객체 전체가 없으면 안전하게 공개할 값을 확인하지 못한 것이며 무료라는 뜻이 아닙니다.

이 객체는 다음 위치에 포함될 수 있습니다.

* 비동기 이미지 작업 조회 `GET /v1/images/generations/{task_id}`
* 비동기 동영상 작업 조회 `GET /v1/videos/generations/{task_id}`
* 작업 Webhook의 `data.billing`
* 지원되는 비스트리밍 동기 이미지 생성 또는 편집 응답의 최상위 `billing`

비동기 작업은 완료 후 작업 조회를 최종 청구 금액의 대체 경로로 사용하세요. 스트리밍 이미지 응답, 지원되지 않는 공급자 응답 형식, Playground 요청, 지연 일괄 청구에서는 생략될 수 있습니다.

## 오류

| 상태            | 코드                      | 의미                                                  |
| ------------- | ----------------------- | --------------------------------------------------- |
| `400`         | `invalid_request_error` | 지원되지 않는 쿼리 파라미터 또는 잘못된 `type` / `limit`             |
| `401` / `403` | 상황에 따라 다름               | API Key가 잘못되었거나 만료 또는 제한되었거나, 해당 계정 또는 그룹을 사용할 수 없음 |
| `404`         | `model_not_found`       | 이 API Key에서 정확한 모델 ID를 사용할 수 없음                     |
| `503`         | `pricing_unavailable`   | 고객 가격을 안전하게 불러올 수 없으며 공개 가격으로 대체하지 않음               |

응답에는 `Cache-Control: private, no-store`가 설정됩니다.