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

# 模型定价

> 通过 /v1/models/pricing 获取权威模型价格

当你需要价格，而不只是模型可见性时，用这条路由。

`/v1/models/pricing` 返回某个模型的单个权威价格对象，不会列出全部渠道的价格。
如果同一个模型可能路由到多个渠道，PipeLLM 只会在这些渠道能收敛到一个权威
价格时直接返回结果；否则可以通过 `provider` 指定渠道。

## 端点

```text theme={null}
GET https://api.pipellm.ai/v1/models/pricing
```

## 查询参数

| 参数         | 必填 | 说明         |
| ---------- | -- | ---------- |
| `model`    | 是  | 要查询价格的模型名称 |
| `provider` | 否  | 指定模型所属渠道   |

## 说明

* 这条路由只支持 `GET`
* `model` 是必填参数
* 只有一个可见渠道时，直接返回该渠道的价格
* 多个可见渠道的有效价格完全一致时，返回一份统一价格
* 多个可见渠道的有效价格不一致时，请求会返回 `409 Conflict`；可以通过 `provider` 指定渠道

## 请求示例

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl "https://api.pipellm.ai/v1/models/pricing?model=gpt-5" \
      -H "Authorization: Bearer $PIPELLM_API_KEY"
    ```
  </Tab>

  <Tab title="cURL（带 selector）">
    ```bash theme={null}
    curl "https://api.pipellm.ai/v1/models/pricing?model=gpt-5&provider=openai" \
      -H "Authorization: Bearer $PIPELLM_API_KEY"
    ```
  </Tab>
</Tabs>

## 响应格式

```json theme={null}
{
  "object": "pricing",
  "data": {
    "id": "gpt-5",
    "display_name": "Gpt 5",
    "type_target": "openai",
    "provider": "openai",
    "pricing": {
      "kind": "token",
      "text": {
        "prompt": "0.000003",
        "completion": "0.000015",
        "internal_reasoning": "0.000015"
      },
      "cache": {
        "read": "0.000001",
        "write": "0.00000375",
        "write_1h": "0.0000075"
      },
      "tiers": {
        "over_200k": {
          "text": {
            "prompt": "0.0000055",
            "completion": "0.000022",
            "internal_reasoning": "0.000022"
          }
        }
      }
    }
  }
}
```

## 响应字段

| 字段                  | 类型     | 说明                               |
| ------------------- | ------ | -------------------------------- |
| `object`            | string | 固定值 `"pricing"`                  |
| `data.id`           | string | API 请求里使用的模型名称                   |
| `data.display_name` | string | 基于模型名称自动生成的人类可读名称                |
| `data.type_target`  | string | 这条模型对外暴露的协议族                     |
| `data.provider`     | string | 当请求已经定位到单一渠道，或显式指定了 provider 时返回 |
| `data.pricing`      | object | 权威价格对象                           |

## 什么情况下会返回歧义

当以下条件同时满足时，PipeLLM 会返回 `409 Conflict`：

* 同一个 `model` 匹配到多条可见映射
* 这些映射的价格并不一致
* 你又没有通过 `provider` 指定渠道

这是刻意设计的行为。只要路由层真实可能选到不同价格的映射，API 就不会伪造一个
“代表价格”。