X-Agents/teams/api/model-api.md

# Model Settings 接口文档

## 接口列表

### 1. 获取模型列表

**接口地址：** `GET /model/list`

**返回参数：**
```json
{
  "list": [
    {
      "id": "xxx-xxx-xxx",
      "name": "OpenAI",
      "model_type": "chat",
      "provider": "OpenAI",
      "model": "gpt-4o",
      "api_key": "sk-xxx",
      "base_url": "https://api.openai.com",
      "api_endpoint": "/v1/chat/completions",
      "status": "active",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ]
}
```

---

### 2. 获取模型详情

**接口地址：** `GET /model/:id`

**返回参数：**
```json
{
  "id": "xxx-xxx-xxx",
  "name": "OpenAI",
  "model_type": "chat",
  "provider": "OpenAI",
  "model": "gpt-4o",
  "api_key": "sk-xxx",
  "base_url": "https://api.openai.com",
  "api_endpoint": "/v1/chat/completions",
  "status": "active",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}
```

---

### 3. 创建模型

**接口地址：** `POST /model/add`

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 是 | 模型名称 |
| model_type | string | 是 | 模型类型：chat/embedding/rerank/vlm |
| provider | string | 是 | 提供商：OpenAI/Ollama |
| model | string | 是 | 模型标识，如 gpt-4o |
| api_key | string | 是 | API 密钥 |
| base_url | string | 是 | 基础 URL |
| api_endpoint | string | 否 | API 端点路径 |

**请求示例：**
```json
{
  "name": "OpenAI",
  "model_type": "chat",
  "provider": "OpenAI",
  "model": "gpt-4o",
  "api_key": "sk-xxx",
  "base_url": "https://api.openai.com",
  "api_endpoint": "/v1/chat/completions"
}
```

**返回参数：**
```json
{
  "id": "xxx-xxx-xxx",
  "name": "OpenAI",
  "model_type": "chat",
  "provider": "OpenAI",
  "model": "gpt-4o",
  "api_key": "sk-xxx",
  "base_url": "https://api.openai.com",
  "api_endpoint": "/v1/chat/completions",
  "status": "active",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}
```

---

### 4. 更新模型

**接口地址：** `PUT /model/:id`

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 否 | 模型名称 |
| model_type | string | 否 | 模型类型：chat/embedding/rerank/vlm |
| provider | string | 否 | 提供商：OpenAI/Ollama |
| model | string | 否 | 模型标识 |
| api_key | string | 否 | API 密钥 |
| base_url | string | 否 | 基础 URL |
| api_endpoint | string | 否 | API 端点路径 |
| status | string | 否 | 状态：active/inactive |

**请求示例：**
```json
{
  "name": "OpenAI Updated",
  "model_type": "chat",
  "provider": "OpenAI",
  "model": "gpt-4o",
  "api_key": "sk-xxx",
  "base_url": "https://api.openai.com",
  "api_endpoint": "/v1/chat/completions",
  "status": "active"
}
```

---

### 5. 删除模型

**接口地址：** `DELETE /model/:id`

**返回参数：**
```json
{
  "success": true
}
```

---

### 6. 测试连接

**接口地址：** `POST /model/test`

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| provider | string | 是 | 提供商：OpenAI/Ollama |
| model | string | 是 | 模型标识 |
| api_key | string | 是 | API 密钥 |
| base_url | string | 是 | 基础 URL |
| api_endpoint | string | 否 | API 端点路径 |

**请求示例：**
```json
{
  "provider": "OpenAI",
  "model": "gpt-4o",
  "api_key": "sk-xxx",
  "base_url": "https://api.openai.com",
  "api_endpoint": "/v1/chat/completions"
}
```

**返回参数：**
```json
{
  "success": true,
  "message": "Connection successful"
}
```

或失败时：
```json
{
  "success": false,
  "message": "HTTP 401: Unauthorized"
}
```

---

## 数据结构

### ModelInfo 模型信息

| 字段 | 类型 | 说明 |
|------|------|------|
| id | string | 主键 UUID |
| name | string | 模型名称 |
| model_type | string | 模型类型：chat/embedding/rerank/vlm |
| provider | string | 提供商：OpenAI/Ollama |
| model | string | 模型标识 |
| api_key | string | API 密钥 |
| base_url | string | 基础 URL |
| api_endpoint | string | API 端点路径 |
| status | string | 状态：active/inactive |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |