# LLM API 转发平台 API 开发文档

---

## 目录

1. [简介](#1-简介)
2. [认证与授权](#2-认证与授权)
   - [2.1 认证令牌（Auth Token）](#21-认证令牌auth-token)
   - [2.2 访问令牌（Access Token）](#22-访问令牌access-token)
3. [API 概览](#3-api-概览)
   - [3.1 客户用户 API](#31-客户用户-api)
   - [3.2 管理员 API](#32-管理员-api)
4. [API 详细说明](#4-api-详细说明)
   - [4.1 认证 API](#41-认证-api)
     - [4.1.1 获取访问令牌](#411-获取访问令牌)
   - [4.2 客户用户 API](#42-客户用户-api)
     - [4.2.1 发送提示词请求](#421-发送提示词请求)
   - [4.3 管理员 API](#43-管理员-api)
     - [4.3.1 LLM 提供商管理](#431-llm-提供商管理)
       - [4.3.1.1 新增 LLM 提供商](#4311-新增-llm-提供商)
       - [4.3.1.2 修改 LLM 提供商](#4312-修改-llm-提供商)
       - [4.3.1.3 删除 LLM 提供商](#4313-删除-llm-提供商)
       - [4.3.1.4 获取 LLM 提供商列表](#4314-获取-llm-提供商列表)
     - [4.3.2 客户用户管理](#432-客户用户管理)
       - [4.3.2.1 新增客户用户](#4321-新增客户用户)
       - [4.3.2.2 修改客户用户](#4322-修改客户用户)
       - [4.3.2.3 删除客户用户](#4323-删除客户用户)
       - [4.3.2.4 获取客户用户列表](#4324-获取客户用户列表)
     - [4.3.3 生成认证令牌](#433-生成认证令牌)
5. [请求与响应格式](#5-请求与响应格式)
   - [5.1 通用请求头](#51-通用请求头)
   - [5.2 响应格式](#52-响应格式)
6. [错误代码](#6-错误代码)
7. [安全性考虑](#7-安全性考虑)
8. [示例](#8-示例)
   - [8.1 获取访问令牌示例](#81-获取访问令牌示例)
   - [8.2 发送提示词请求示例](#82-发送提示词请求示例)
9. [结论](#9-结论)

---

## 1. 简介

本文档详细描述了 LLM API 转发平台的 API 接口规范，旨在指导开发者基于 Laravel、MySQL 和 Redis 技术栈，实现平台的 API 功能。平台提供了基于令牌的 LLM 调用服务，支持多层级管理员管理和 LLM 提供商的动态配置。

---

## 2. 认证与授权

平台采用基于令牌的认证机制，包括长期有效的**认证令牌（Auth Token）**和短期有效的**访问令牌（Access Token）**。

### 2.1 认证令牌（Auth Token）

- **用途**：客户用户使用认证令牌获取访问令牌。
- **特点**：
  - 由管理员生成并分发给客户用户。
  - 长期有效，或由管理员设定过期时间。

### 2.2 访问令牌（Access Token）

- **用途**：客户用户使用访问令牌访问受保护的 API 接口。
- **特点**：
  - 由客户用户使用认证令牌获取。
  - 短期有效（如 1 小时），存储在 Redis 中，支持自动过期和动态注销。

---

## 3. API 概览

### 3.1 客户用户 API

- **获取访问令牌**
  - `POST /api/auth/token`
- **发送提示词请求**
  - `POST /api/llm/request`

### 3.2 管理员 API

- **LLM 提供商管理**
  - 新增 LLM 提供商：`POST /api/admin/llm-providers`
  - 修改 LLM 提供商：`PUT /api/admin/llm-providers/{id}`
  - 删除 LLM 提供商：`DELETE /api/admin/llm-providers/{id}`
  - 获取 LLM 提供商列表：`GET /api/admin/llm-providers`
- **客户用户管理**
  - 新增客户用户：`POST /api/admin/clients`
  - 修改客户用户：`PUT /api/admin/clients/{id}`
  - 删除客户用户：`DELETE /api/admin/clients/{id}`
  - 获取客户用户列表：`GET /api/admin/clients`
- **生成认证令牌**
  - `POST /api/admin/clients/{id}/auth-token`

---

## 4. API 详细说明

### 4.1 认证 API

#### 4.1.1 获取访问令牌

- **URL**：`/api/auth/token`
- **方法**：`POST`
- **描述**：使用认证令牌获取短期访问令牌。

**请求参数**：

- **Header**：
  - `Content-Type: application/json`
- **Body**：
  ```json
  {
    "auth_token": "string"
  }
  ```
  - `auth_token`（必填）：管理员分发的认证令牌。

**响应示例**：

- **成功**：
  ```json
  {
    "access_token": "string",
    "expires_in": 3600
  }
  ```
  - `access_token`：短期访问令牌。
  - `expires_in`：令牌有效期，单位为秒。

- **失败**：
  ```json
  {
    "error": "invalid_auth_token",
    "message": "认证令牌无效。"
  }
  ```

### 4.2 客户用户 API

#### 4.2.1 发送提示词请求

- **URL**：`/api/llm/request`
- **方法**：`POST`
- **描述**：使用访问令牌向绑定的 LLM 提供商发送提示词请求。

**请求参数**：

- **Header**：
  - `Content-Type: application/json`
  - `Authorization: Bearer {access_token}`
- **Body**：
  ```json
  {
    "prompt": "string"
  }
  ```
  - `prompt`（必填）：提示词内容。

**响应示例**：

- **成功**：
  ```json
  {
    "response": "LLM 提供商返回的响应内容"
  }
  ```
- **失败**：
  ```json
  {
    "error": "invalid_access_token",
    "message": "访问令牌无效或已过期。"
  }
  ```

### 4.3 管理员 API

> **注意**：管理员 API 需要使用管理员的身份认证（如 JWT Token 或 Session），具体认证方式可根据系统需求设计。

#### 4.3.1 LLM 提供商管理

##### 4.3.1.1 新增 LLM 提供商

- **URL**：`/api/admin/llm-providers`
- **方法**：`POST`
- **描述**：新增一个 LLM 提供商。

**请求参数**：

- **Header**：
  - `Content-Type: application/json`
- **Body**：
  ```json
  {
    "name": "string",
    "service_name": "string",
    "api_url": "string",
    "api_token": "string"
  }
  ```
  - `name`（必填）：提供商名称。
  - `service_name`（必填）：对应的服务逻辑名称。
  - `api_url`（必填）：提供商的 API 接口地址。
  - `api_token`（必填）：调用提供商 API 所需的令牌。

**响应示例**：

- **成功**：
  ```json
  {
    "id": 1,
    "name": "OpenAI",
    "service_name": "OpenAIService",
    "api_url": "https://api.openai.com/v1/engines/davinci/completions",
    "api_token": "sk-xxxxx",
    "created_at": "2023-10-01T12:00:00Z"
  }
  ```
- **失败**：
  ```json
  {
    "error": "validation_error",
    "message": "提供商名称已存在。"
  }
  ```

##### 4.3.1.2 修改 LLM 提供商

- **URL**：`/api/admin/llm-providers/{id}`
- **方法**：`PUT`
- **描述**：修改指定的 LLM 提供商信息。

**请求参数**：

- **路径参数**：
  - `id`（必填）：LLM 提供商的 ID。
- **Header**：
  - `Content-Type: application/json`
- **Body**：
  ```json
  {
    "name": "string",
    "service_name": "string",
    "api_url": "string",
    "api_token": "string"
  }
  ```
  - 参数同新增接口，可选填。

**响应示例**：

- **成功**：
  ```json
  {
    "id": 1,
    "name": "OpenAI",
    "service_name": "OpenAIService",
    "api_url": "https://api.openai.com/v1/engines/davinci/completions",
    "api_token": "sk-xxxxx",
    "updated_at": "2023-10-02T12:00:00Z"
  }
  ```
- **失败**：
  ```json
  {
    "error": "not_found",
    "message": "LLM 提供商不存在。"
  }
  ```

##### 4.3.1.3 删除 LLM 提供商

- **URL**：`/api/admin/llm-providers/{id}`
- **方法**：`DELETE`
- **描述**：删除指定的 LLM 提供商。

**请求参数**：

- **路径参数**：
  - `id`（必填）：LLM 提供商的 ID。

**响应示例**：

- **成功**：
  ```json
  {
    "message": "LLM 提供商已删除。"
  }
  ```
- **失败**：
  ```json
  {
    "error": "not_found",
    "message": "LLM 提供商不存在。"
  }
  ```

##### 4.3.1.4 获取 LLM 提供商列表

- **URL**：`/api/admin/llm-providers`
- **方法**：`GET`
- **描述**：获取所有 LLM 提供商的列表。

**响应示例**：

- **成功**：
  ```json
  [
    {
      "id": 1,
      "name": "OpenAI",
      "service_name": "OpenAIService",
      "api_url": "https://api.openai.com/v1/engines/davinci/completions",
      "created_at": "2023-10-01T12:00:00Z"
    },
    {
      "id": 2,
      "name": "Anthropic",
      "service_name": "AnthropicService",
      "api_url": "https://api.anthropic.com/v1/complete",
      "created_at": "2023-10-01T13:00:00Z"
    }
  ]
  ```

#### 4.3.2 客户用户管理

##### 4.3.2.1 新增客户用户

- **URL**：`/api/admin/clients`
- **方法**：`POST`
- **描述**：新增一个客户用户，并绑定 LLM 提供商。

**请求参数**：

- **Header**：
  - `Content-Type: application/json`
- **Body**：
  ```json
  {
    "name": "string",
    "llm_provider_id": 1
  }
  ```
  - `name`（必填）：客户用户名称。
  - `llm_provider_id`（必填）：绑定的 LLM 提供商 ID。

**响应示例**：

- **成功**：
  ```json
  {
    "id": 1001,
    "name": "Client A",
    "llm_provider_id": 1,
    "created_at": "2023-10-01T14:00:00Z"
  }
  ```
- **失败**：
  ```json
  {
    "error": "validation_error",
    "message": "客户用户名称已存在。"
  }
  ```

##### 4.3.2.2 修改客户用户

- **URL**：`/api/admin/clients/{id}`
- **方法**：`PUT`
- **描述**：修改指定的客户用户信息。

**请求参数**：

- **路径参数**：
  - `id`（必填）：客户用户的 ID。
- **Header**：
  - `Content-Type: application/json`
- **Body**：
  ```json
  {
    "name": "string",
    "llm_provider_id": 2
  }
  ```
  - 参数可选填。

**响应示例**：

- **成功**：
  ```json
  {
    "id": 1001,
    "name": "Client A Updated",
    "llm_provider_id": 2,
    "updated_at": "2023-10-02T14:00:00Z"
  }
  ```
- **失败**：
  ```json
  {
    "error": "not_found",
    "message": "客户用户不存在。"
  }
  ```

##### 4.3.2.3 删除客户用户

- **URL**：`/api/admin/clients/{id}`
- **方法**：`DELETE`
- **描述**：删除指定的客户用户。

**请求参数**：

- **路径参数**：
  - `id`（必填）：客户用户的 ID。

**响应示例**：

- **成功**：
  ```json
  {
    "message": "客户用户已删除。"
  }
  ```
- **失败**：
  ```json
  {
    "error": "not_found",
    "message": "客户用户不存在。"
  }
  ```

##### 4.3.2.4 获取客户用户列表

- **URL**：`/api/admin/clients`
- **方法**：`GET`
- **描述**：获取所有客户用户的列表。

**响应示例**：

- **成功**：
  ```json
  [
    {
      "id": 1001,
      "name": "Client A",
      "llm_provider_id": 1,
      "created_at": "2023-10-01T14:00:00Z"
    },
    {
      "id": 1002,
      "name": "Client B",
      "llm_provider_id": 2,
      "created_at": "2023-10-01T15:00:00Z"
    }
  ]
  ```

#### 4.3.3 生成认证令牌

- **URL**：`/api/admin/clients/{id}/auth-token`
- **方法**：`POST`
- **描述**：为指定的客户用户生成一个新的认证令牌。

**请求参数**：

- **路径参数**：
  - `id`（必填）：客户用户的 ID。

**响应示例**：

- **成功**：
  ```json
  {
    "client_id": 1001,
    "auth_token": "abcd1234efgh5678ijkl9012mnop3456qrst7890uvwx1234yzab5678cdef9012",
    "created_at": "2023-10-01T16:00:00Z"
  }
  ```
- **失败**：
  ```json
  {
    "error": "not_found",
    "message": "客户用户不存在。"
  }
  ```

---

## 5. 请求与响应格式

### 5.1 通用请求头

- `Content-Type: application/json`
- 对于需要认证的接口，使用以下方式传递令牌：
  - **客户用户访问令牌**：`Authorization: Bearer {access_token}`
  - **管理员认证**：根据系统设计，可采用 `Authorization: Bearer {admin_token}`，或使用 Session/Cookie。

### 5.2 响应格式

- 所有响应均为 JSON 格式。
- 成功响应：
  - HTTP 状态码为 `200` 或 `201`，响应体为请求的数据。
- 失败响应：
  - HTTP 状态码为 `4xx` 或 `5xx`，响应体包含 `error` 和 `message` 字段。

**错误响应示例**：

```json
{
  "error": "invalid_request",
  "message": "请求参数缺失。"
}
```

---

## 6. 错误代码

| 错误代码                | HTTP 状态码 | 描述                           |
|------------------------|-------------|------------------------------|
| `invalid_request`      | 400         | 请求无效，参数缺失或格式错误。 |
| `unauthorized`         | 401         | 未授权，令牌无效或未提供。     |
| `forbidden`            | 403         | 禁止访问，没有权限。           |
| `not_found`            | 404         | 资源不存在。                   |
| `validation_error`     | 422         | 请求参数验证失败。             |
| `server_error`         | 500         | 服务器内部错误。               |

---

## 7. 安全性考虑

- **HTTPS 加密**：所有 API 请求必须通过 HTTPS 协议，确保数据传输的安全性。
- **令牌安全**：
  - 认证令牌和访问令牌应保密存储，避免泄露。
  - 令牌在传输过程中只能通过 `Authorization` 头部发送，避免在 URL 或请求体中传递。
- **权限控制**：
  - 后端需要验证令牌的有效性和权限，防止未授权的访问。
  - 管理员和客户用户的权限应严格区分，防止越权操作。
- **输入验证**：
  - 对所有输入参数进行严格的格式和类型验证，防止 SQL 注入和 XSS 攻击。
- **错误信息**：
  - 返回的错误信息应简洁明了，避免泄露服务器内部信息。

---

## 8. 示例

### 8.1 获取访问令牌示例

**请求**：

```http
POST /api/auth/token HTTP/1.1
Host: api.yourdomain.com
Content-Type: application/json

{
  "auth_token": "abcd1234efgh5678ijkl9012mnop3456qrst7890uvwx1234yzab5678cdef9012"
}
```

**响应**：

```json
{
  "access_token": "wxyz1234abcd5678efgh9012ijkl3456mnop7890qrst1234uvwx5678yzab9012",
  "expires_in": 3600
}
```

### 8.2 发送提示词请求示例

**请求**：

```http
POST /api/llm/request HTTP/1.1
Host: api.yourdomain.com
Content-Type: application/json
Authorization: Bearer wxyz1234abcd5678efgh9012ijkl3456mnop7890qrst1234uvwx5678yzab9012

{
  "prompt": "Hello, how are you?"
}
```

**响应**：

```json
{
  "response": "I'm doing well, thank you for asking!"
}
```

---

## 9. 结论

本 API 开发文档详细描述了 LLM API 转发平台的各项接口、请求与响应格式、错误代码和安全性考虑。开发者应根据本规范进行接口的开发与测试，确保系统的稳定性和安全性。

---

**注意**：在实际开发中，可能需要根据具体的业务需求和技术选型，进一步完善和调整本 API 文档。

---

# 附录

## 技术栈说明

- **Laravel**：PHP 的优秀框架，提供了丰富的功能和高效的开发体验。
- **MySQL**：关系型数据库，存储平台的核心数据。
- **Redis**：高性能的内存缓存数据库，用于存储短期令牌和支持动态注销。

## 开发建议

- **代码规范**：遵循 Laravel 和 PHP 的代码规范，使用 PSR 标准。
- **日志记录**：重要的操作和错误需要记录日志，便于追踪和排查问题。
- **单元测试**：编写单元测试和集成测试，确保接口的稳定性和可靠性。
- **性能优化**：关注接口的性能，使用缓存、异步等方式优化响应速度。

---

**感谢阅读本 API 开发文档，如有任何疑问或建议，请与项目组联系。**