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

# 模型列表

> GET /v1/models — 获取平台可用模型列表

获取平台当前可用的模型列表及其能力信息。用于发现可在 `/v1/chat/completions` 和 `/v1/agents/run` 中使用的模型。

```
GET https://api.profy.cn/v1/models
```

## 认证

<ParamField header="Authorization" type="string" required>
  `Bearer sk-pro-xxxx`（API Key）
</ParamField>

## 请求示例

<CodeGroup>
  ```python Python theme={null}
  from profy import Profy

  async with Profy(api_key="sk-pro-your-key") as client:
      models = await client.models.list()
      for m in models:
          print(f"{m['id']}: {m['name']}")
          caps = m.get("capabilities", {})
          if caps.get("supportsVision"):
              print("  支持视觉")
          if caps.get("supportsTools"):
              print("  支持工具调用")
  ```

  ```typescript TypeScript theme={null}
  import { Profy } from "@profy-ai/sdk";

  const client = new Profy({ apiKey: "sk-pro-your-key" });

  const models = await client.models.list();
  for (const m of models) {
    console.log(`${m.id}: ${m.name}`);
    if (m.capabilities?.supportsVision) console.log("  支持视觉");
    if (m.capabilities?.supportsTools) console.log("  支持工具调用");
  }
  ```

  ```bash curl theme={null}
  curl https://api.profy.cn/v1/models \
    -H "Authorization: Bearer sk-pro-your-key"
  ```
</CodeGroup>

## 响应

```json theme={null}
{
  "models": [
    {
      "id": "deepseek-v3",
      "type": "model",
      "name": "DeepSeek V3",
      "capabilities": {
        "omitTemperature": false,
        "fixedTemperature": null,
        "requiresReasoning": false,
        "maxInputTokens": 65536,
        "maxOutputTokens": 8192,
        "supportsTools": true,
        "supportsVision": false
      }
    },
    {
      "id": "claude-sonnet-4-20250514",
      "type": "model",
      "name": "Claude Sonnet 4",
      "capabilities": {
        "omitTemperature": false,
        "fixedTemperature": null,
        "requiresReasoning": false,
        "maxInputTokens": 200000,
        "maxOutputTokens": 16384,
        "supportsTools": true,
        "supportsVision": true
      }
    },
    {
      "id": "profy-financial-advisor",
      "type": "expert",
      "name": "金融理财顾问",
      "description": "专业的金融分析与理财规划专家",
      "created": 1752825600,
      "owned_by": "creator-xxx"
    }
  ]
}
```

## 模型对象

| 字段             | 类型       | 说明                                                                                         |
| -------------- | -------- | ------------------------------------------------------------------------------------------ |
| `id`           | `string` | 模型标识符，在 API 调用中使用此值                                                                        |
| `type`         | `string` | `"model"`（裸 LLM 模型）或 `"expert"`（袋袋专家，通过 `profy-<identifier>` 在 `/v1/chat/completions` 中使用） |
| `name`         | `string` | 模型显示名称                                                                                     |
| `capabilities` | `object` | 模型能力描述，仅 `type: "model"` 返回（见下表）                                                           |
| `description`  | `string` | 专家描述，仅 `type: "expert"` 返回                                                                 |
| `created`      | `number` | 创建时间戳（秒），仅 `type: "expert"` 返回                                                             |
| `owned_by`     | `string` | 创作者标识，仅 `type: "expert"` 返回                                                                |

## Capabilities 字段

| 字段                  | 类型               | 说明                              |
| ------------------- | ---------------- | ------------------------------- |
| `omitTemperature`   | `boolean`        | 是否应省略 temperature 参数            |
| `fixedTemperature`  | `number \| null` | 固定 temperature 值。`null` 表示可自由设置 |
| `requiresReasoning` | `boolean`        | 是否为推理模型（会产生 thinking 输出）        |
| `maxInputTokens`    | `number \| null` | 最大输入 token 数                    |
| `maxOutputTokens`   | `number \| null` | 最大输出 token 数                    |
| `supportsTools`     | `boolean`        | 是否支持 Function Calling           |
| `supportsVision`    | `boolean`        | 是否支持图片理解                        |

## 使用场景

### 按能力筛选模型

```python theme={null}
async with Profy(api_key="sk-pro-your-key") as client:
    models = await client.models.list()

    tool_models = [m for m in models if m["capabilities"]["supportsTools"]]
    vision_models = [m for m in models if m["capabilities"]["supportsVision"]]

    best_context = max(
        models,
        key=lambda m: m["capabilities"].get("maxInputTokens") or 0,
    )
```

### 筛选专家模型

```python theme={null}
async with Profy(api_key="sk-pro-your-key") as client:
    models = await client.models.list()

    expert_models = [m for m in models if m.get("type") == "expert"]
    for e in expert_models:
        print(f"{e['id']}: {e['name']} — {e.get('description', '')}")
```

### 处理 temperature 差异

不同模型对 temperature 参数的支持不同。在调用前检查 capabilities 可以避免请求被拒绝：

```python theme={null}
caps = model_map[target]["capabilities"]

params = {"model": target, "messages": messages}

if not caps["omitTemperature"]:
    if caps["fixedTemperature"] is not None:
        params["temperature"] = caps["fixedTemperature"]
    else:
        params["temperature"] = 0.7

resp = await client.chat.completions.create(**params)
```

<Tip>
  平台可用的模型列表会不定期更新。建议你的应用在启动时或定期调用此端点以获取最新列表。
</Tip>

## 错误码

| HTTP 状态码 | 说明   |
| -------- | ---- |
| `401`    | 认证失败 |

## 下一步

<CardGroup cols={2}>
  <Card title="对话补全" icon="comments" href="/zh/developers/api/chat-completions">
    使用模型进行对话补全
  </Card>

  <Card title="调用专家" icon="robot" href="/zh/developers/api/agents-run">
    调用专家 Agent
  </Card>
</CardGroup>