> ## 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 获取 PipeLLM 统一模型目录

用这条路由获取当前账号可见的模型 ID。`/v1/models` 现在是纯目录接口，
只返回模型身份和协议元数据，不再返回价格。

如果你需要价格，请改用 [`/v1/models/pricing`](/api-reference/model-pricing.zh)。

## 端点

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

## 认证

使用标准的 PipeLLM API Key 请求头：

| Header          | 示例                        |
| --------------- | ------------------------- |
| `Authorization` | `Bearer $PIPELLM_API_KEY` |
| `x-api-key`     | `$PIPELLM_API_KEY`        |

## 说明

* 这条路由只支持 `GET`
* 返回的是 PipeLLM 统一目录 schema
* `hidden` 和 `unlisted` 的模型会在返回前被过滤掉
* 结果会按模型 ID 排序
* 价格字段被刻意移出目录接口，避免同一个模型映射到多个平台时误导调用方以为存在单一权威价格

## 请求示例

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

  <Tab title="Python">
    ```python theme={null}
    import os
    import requests

    response = requests.get(
        "https://api.pipellm.ai/v1/models",
        headers={"Authorization": f"Bearer {os.getenv('PIPELLM_API_KEY')}"},
    )

    response.raise_for_status()
    payload = response.json()

    for model in payload["data"]:
        print(model["id"], model["type_target"])
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const response = await fetch("https://api.pipellm.ai/v1/models", {
      headers: {
        Authorization: `Bearer ${process.env.PIPELLM_API_KEY}`,
      },
    });

    if (!response.ok) {
      throw new Error(`Request failed: ${response.status}`);
    }

    const payload = await response.json();
    for (const model of payload.data) {
      console.log(model.id, model.type_target);
    }
    ```
  </Tab>
</Tabs>

## 响应格式

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "id": "gpt-5",
      "display_name": "Gpt 5",
      "type_target": "openai",
      "created_at": "2025-05-14T00:00:00Z"
    },
    {
      "id": "claude-sonnet-4-6",
      "display_name": "Claude Sonnet 4.6",
      "type_target": "anthropic",
      "created_at": "2025-03-01T00:00:00Z"
    }
  ],
  "total": 2
}
```

## 响应字段

| 字段                    | 类型      | 说明                                            |
| --------------------- | ------- | --------------------------------------------- |
| `object`              | string  | 固定值 `"list"`                                  |
| `data`                | array   | 模型目录对象数组                                      |
| `data[].id`           | string  | API 请求里使用的模型 ID                               |
| `data[].display_name` | string  | 基于模型 ID 自动生成的人类可读名称                           |
| `data[].type_target`  | string  | 这条模型对外暴露的协议族，例如 `openai`、`anthropic`、`gemini` |
| `data[].created_at`   | string  | 从模型元数据选出的 RFC3339 时间戳                         |
| `total`               | integer | 返回的模型总数                                       |

## 这条路由适合做什么

用 `/v1/models` 可以：

* 给你的 UI 生成模型选择器
* 判断某个模型当前账号是否可见
* 确认模型对外暴露在哪个协议族下

如果你需要权威价格，请改用 [`/v1/models/pricing`](/api-reference/model-pricing.zh)。

## 相关文档

<Columns cols={3}>
  <Card title="模型定价" icon="wallet" href="/api-reference/model-pricing.zh">
    按模型、provider 或平台映射查询权威价格
  </Card>

  <Card title="路由与协议" icon="route" href="/guides/routing-protocols.zh">
    了解模型协议族如何影响请求格式
  </Card>

  <Card title="开发工具" icon="terminal" href="/integrations/overview.zh">
    在 Claude Code、OpenCode、OpenClaw 和 LangChain 中使用这些模型 ID
  </Card>
</Columns>