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

## 计费方式

PipeLLM 从你的控制台余额扣费。余额不足时请求在处理前就返回 `402`，见
[错误与排查](/zh/api-reference/errors)。

各模型的具体费率在 [模型库](https://pipellm.ai/models)。本接口以程序化方式返回同一组数字。
文档刻意不复述费率，因此这里不存在过期的风险。

视频在调用 [`POST /v2/videos`](/zh/api-reference/video/create) 时按美元计费。报价在创建时
锁定，之后即使价格被修改也不变；查询和取消不计费。

## 端点

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

## 查询参数

<ParamField query="model" type="string" required>
  要查询价格的模型 ID。
</ParamField>

<ParamField query="provider" type="string">
  同一 ID 存在多个价格时，用 provider 收窄。
</ParamField>

<ParamField query="platform_id" type="integer">
  需要精确到某条映射时传入平台 ID。
</ParamField>

## 说明

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

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

  ```bash cURL (provider) theme={"dark"}
  curl "https://api.pipellm.ai/v1/models/pricing?model=gpt-5&provider=openai" \
    -H "Authorization: Bearer $PIPELLM_API_KEY"
  ```
</RequestExample>

## 响应格式

```json theme={"dark"}
{
  "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 就不会伪造一个
“代表价格”。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.