> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Octop 提供商 API：配置模型提供商与模型

配置模型提供商，选择可用模型，并控制专家使用的默认模型。

## 权限

已登录用户可以列出全部提供商，并读取自己可选的模型。创建、更新、删除、测试提供商，以及设置全局默认模型，需要 `providers` 权限。写操作走 `/api/admin/providers`。

OpenAI 兼容提供商可以选择 Responses（`/v1/responses`）或 Chat Completions。服务启动时会同步新的预置模型，腾讯云通道包含混元 HY4。

## 端点

| 方法     | 路径                           | 描述                           |
| ------ | ---------------------------- | ---------------------------- |
| GET    | `/providers`                 | 列出提供商（已登录用户，只读）              |
| GET    | `/providers/resolved`        | 列出当前用户可选的已启用模型               |
| GET    | `/providers/active-model`    | 获取全局默认模型                     |
| PUT    | `/providers/active-model`    | 设置全局默认模型（需要 `providers` 权限）  |
| POST   | `/admin/providers`           | 添加提供商（需要 `providers` 权限）     |
| PATCH  | `/admin/providers/{id}`      | 更新提供商（需要 `providers` 权限）     |
| DELETE | `/admin/providers/{id}`      | 删除提供商（需要 `providers` 权限）     |
| POST   | `/admin/providers/{id}/test` | 测试已保存的提供商（需要 `providers` 权限） |

## 创建提供商

### OpenAI

```bash
curl -X POST http://127.0.0.1:8088/api/admin/providers \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "openai",
    "kind": "openai",
    "base_url": "https://api.openai.com/v1",
    "api_key": "sk-..."
  }'
```

### 本地 Ollama

```bash
curl -X POST http://127.0.0.1:8088/api/admin/providers \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "local-ollama",
    "kind": "ollama",
    "base_url": "http://127.0.0.1:11434"
  }'
```

### DashScope

```bash
curl -X POST http://127.0.0.1:8088/api/admin/providers \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "dashscope",
    "kind": "dashscope",
    "api_key": "sk-..."
  }'
```


> **说明**
> 
> API 密钥会加密存储。更新密钥时，向 `PATCH /api/admin/providers/{id}` 提交新的 `api_key`。
> 


## 测试提供商

创建提供商后，调用 `test` 端点验证连接是否健康。Octop 会发送一次轻量模型请求；如果是嵌入模型，则探测 embeddings 端点。对于常见的鉴权、余额、限流或服务不可用错误，Octop 会尽量返回本地化处理建议，而不是只暴露原始上游错误。

```bash
curl -X POST http://127.0.0.1:8088/api/admin/providers/1/test \
  -H 'Authorization: Bearer <token>'
```

响应：

```json
{"ok": true, "latency_ms": 312}
```

如需测试指定聊天或嵌入模型，可在 JSON 请求体中传入 `model_id` 或 `embedding: true`。

或失败时返回错误详情。

## 列出可用模型

```bash
curl http://127.0.0.1:8088/api/providers/resolved \
  -H 'Authorization: Bearer <token>'
```

返回当前用户可选的已启用模型，每项包含 `provider_name` 和 `model`。

## 设置活动模型

需要 `providers` 权限：

```bash
curl -X PUT http://127.0.0.1:8088/api/providers/active-model \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"provider_name": "openai", "model": "gpt-4o"}'
```


> **注意**
> 
> 删除仍被一个或多个专家引用的提供商将返回 `409 PROVIDER_REFERENCED`。请先将受影响专家重新指定到其他提供商。
> 



**管理员共享提供商**

有 `providers` 权限的用户通过 `/api/admin/providers` 管理提供商。这些提供商对已登录用户可见，普通用户只能列出，不能修改或删除。

## Agent Client Protocol（ACP）

| 方法     | 路径                   | 描述            |
| ------ | -------------------- | ------------- |
| GET    | `/acp`               | 列出 ACP 运行时    |
| PUT    | `/acp`               | 添加/更新 ACP 运行时 |
| GET    | `/acp/{runner_name}` | 获取运行时详情       |
| PUT    | `/acp/{runner_name}` | 更新运行时         |
| DELETE | `/acp/{runner_name}` | 删除运行时         |
| GET    | `/agents/{aid}/acp`  | 获取专家的 ACP 配置  |
| PUT    | `/agents/{aid}/acp`  | 设置专家的 ACP 配置  |
