渠道管理模块

功能说明

接口前缀统一为 http(s)://<your-domain>

生产环境应使用 HTTPS 以保证认证令牌。 HTTP 仅建议用于开发环境。

AI 服务提供商渠道的完整管理系统。支持渠道增删改查、批量操作、连通性测试、余额查询、标签管理等功能。包含模型能力同步和渠道复制等高级功能。

🔐 管理员鉴权

获取渠道列表

接口名称：获取渠道列表
HTTP 方法：GET
路径：/api/channel/
鉴权要求：管理员
功能简介：分页获取系统中所有渠道的列表信息，支持按类型、状态过滤和标签模式

💡 请求示例：

const response = await fetch('/api/channel/?p=1&page_size=20&id_sort=false&tag_mode=false&type=1&status=enabled', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  }
});
const data = await response.json();

✅ 成功响应示例：

{
  "success": true,
  "message": "",
  "data": {
    "items": [
      {
        "id": 1,
        "name": "OpenAI渠道",
        "type": 1,
        "status": 1,
        "priority": 10,
        "weight": 100,
        "models": "gpt-3.5-turbo,gpt-4",
        "group": "default",
        "response_time": 1500,
        "test_time": 1640995200
      }
    ],
    "total": 50,
    "type_counts": {
      "1": 20,
      "2": 15,
      "all": 35
    }
  }
}

❗ 失败响应示例：

{
  "success": false,
  "message": "获取渠道列表失败"
}

🧾 字段说明：

p （数字）: 页码，默认为 1
page_size （数字）: 每页数量，默认为 20
id_sort （布尔型）: 是否按 ID 排序，默认按优先级排序
tag_mode （布尔型）: 是否启用标签模式
type （数字）: 渠道类型过滤
status （字符串）: 状态过滤，可选值："enabled"、"disabled"、"all"

搜索渠道

接口名称：搜索渠道
HTTP 方法：GET
路径：/api/channel/search
鉴权要求：管理员
功能简介：根据关键词、分组、模型等条件搜索渠道

💡 请求示例：

const response = await fetch('/api/channel/search?keyword=openai&group=default&model=gpt-4&id_sort=false&tag_mode=false&p=1&page_size=20&type=1&status=enabled', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  }
});
const data = await response.json();

✅ 成功响应示例：

{
  "success": true,
  "message": "",
  "data": {
    "items": [
      {
        "id": 1,
        "name": "OpenAI官方渠道",
        "type": 1,
        "status": 1,
        "models": "gpt-3.5-turbo,gpt-4",
        "group": "default"
      }
    ],
    "total": 1,
    "type_counts": {
      "1": 1,
      "all": 1
    }
  }
}

❗ 失败响应示例：

{    "success": false,    "message": "搜索渠道失败"  }

🧾 字段说明：

keyword （字符串）: 搜索关键词，可匹配渠道名称
group （字符串）: 分组过滤条件
model （字符串）: 模型过滤条件
其他参数与获取渠道列表接口相同

查询渠道模型能力

接口名称：查询渠道模型能力
HTTP 方法：GET
路径：/api/channel/models
鉴权要求：管理员
功能简介：获取系统中所有渠道支持的模型列表

💡 请求示例：

const response = await fetch('/api/channel/models', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  }
});
const data = await response.json();

✅ 成功响应示例：

{
  "success": true,
  "message": "",
  "data": [
    {
      "id": "gpt-3.5-turbo",
      "name": "GPT-3.5 Turbo"
    },
    {
      "id": "gpt-4",
      "name": "GPT-4"
    },
    {
      "id": "claude-3-sonnet",
      "name": "Claude 3 Sonnet"
    }
  ]
}

❗ 失败响应示例：

{
  "success": false,
  "message": "获取模型列表失败"
}

🧾 字段说明：

data （数组）: 模型信息列表

id （字符串）: 模型 ID
name （字符串）: 模型显示名称

查询启用模型能力

接口名称：查询启用模型能力
HTTP 方法：GET
路径：/api/channel/models_enabled
鉴权要求：管理员
功能简介：获取当前启用渠道支持的模型列表

💡 请求示例：

const response = await fetch('/api/channel/models_enabled', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  }
});
const data = await response.json();

✅ 成功响应示例：

{
  "success": true,
  "message": "",
  "data": [
    "gpt-3.5-turbo",
    "gpt-4",
    "claude-3-sonnet"
  ]
}

❗ 失败响应示例：

{
  "success": false,
  "message": "获取启用模型失败"
}

🧾 字段说明：

data （数组）: 启用的模型 ID 列表

获取单个渠道

接口名称：获取单个渠道
HTTP 方法：GET
路径：/api/channel/:id
鉴权要求：管理员
功能简介：获取指定渠道的详细信息，不包含敏感的密钥信息

💡 请求示例：

const response = await fetch('/api/channel/123', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  }
});
const data = await response.json();

✅ 成功响应示例：

{
  "success": true,
  "message": "",
  "data": {
    "id": 123,
    "name": "OpenAI渠道",
    "type": 1,
    "status": 1,
    "priority": 10,
    "weight": 100,
    "models": "gpt-3.5-turbo,gpt-4",
    "group": "default",
    "base_url": "https://api.openai.com",
    "model_mapping": "{}",
    "channel_info": {
      "is_multi_key": false,
      "multi_key_mode": "random"
    }
  }
}

❗ 失败响应示例：

{
  "success": false,
  "message": "渠道不存在"
}

🧾 字段说明：

id （数字）: 渠道 ID，通过 URL 路径传递
返回完整的渠道信息，但不包含密钥字段

批量测试渠道连通性

接口名称：批量测试渠道连通性
HTTP 方法：GET
路径：/api/channel/test
鉴权要求：管理员
功能简介：批量测试所有或指定渠道的连通性和响应时间

💡 请求示例：

const response = await fetch('/api/channel/test?model=gpt-3.5-turbo', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  }
});
const data = await response.json();

✅ 成功响应示例：

{
  "success": true,
  "message": "批量测试完成",
  "data": {
    "total": 10,
    "success": 8,
    "failed": 2,
    "results": [
      {
        "channel_id": 1,
        "channel_name": "OpenAI渠道",
        "success": true,
        "time": 1.25,
        "message": ""
      },
      {
        "channel_id": 2,
        "channel_name": "Claude渠道",
        "success": false,
        "time": 0,
        "message": "连接超时"
      }
    ]
  }
}

❗ 失败响应示例：

{
  "success": false,
  "message": "批量测试失败"
}

🧾 字段说明：

model （字符串）: 可选，指定测试模型
results （数组）: 测试结果列表
- success （布尔型）: 测试是否成功
- time （数字）: 响应时间（秒）

单个渠道测试

接口名称：单个渠道测试
HTTP 方法：GET
路径：/api/channel/test/:id
鉴权要求：管理员
功能简介：测试指定渠道的连通性，支持指定测试模型

💡 请求示例：

const response = await fetch('/api/channel/test/123?model=gpt-4', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  }
});
const data = await response.json();

✅ 成功响应示例：

{
  "success": true,
  "message": "",
  "time": 1.25
}

❗ 失败响应示例：

{
  "success": false,
  "message": "API密钥无效",
  "time": 0.5
}

🧾 字段说明：

id （数字）: 渠道 ID，通过 URL 路径传递
model （字符串）: 可选，指定测试的模型名称
time （数字）: 响应时间（秒）

批量刷新余额

接口名称：批量刷新余额
HTTP 方法：GET
路径：/api/channel/update_balance
鉴权要求：管理员
功能简介：批量更新所有启用渠道的余额信息

💡 请求示例：

const response = await fetch('/api/channel/update_balance', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  }
});
const data = await response.json();

✅ 成功响应示例：

{
  "success": true,
  "message": "批量更新余额完成"
}

❗ 失败响应示例：

{
  "success": false,
  "message": "批量更新余额失败"
}

🧾 字段说明：

无请求参数，系统会自动更新所有启用渠道的余额

单个刷新余额

接口名称：更新指定渠道余额
HTTP 方法：GET
路径：/api/channel/update_balance/:id
鉴权要求：管理员
功能简介：更新指定渠道的余额信息，多密钥渠道不支持余额查询

💡 请求示例：

const response = await fetch('/api/channel/update_balance/123', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  }
});
const data = await response.json();

✅ 成功响应示例：

{
  "success": true,
  "message": "",
  "balance": 25.50
}

❗ 失败响应示例：

{
  "success": false,
  "message": "多密钥渠道不支持余额查询"
}

🧾 字段说明：

id （数字）: 渠道 ID，通过 URL 路径传递
balance （数字）: 更新后的渠道余额

新增渠道

接口名称：新增渠道
HTTP 方法：POST
路径：/api/channel/
鉴权要求：管理员
功能简介：创建新的 AI 服务渠道，支持单个、批量和多密钥模式

💡 请求示例：

const response = await fetch('/api/channel/', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  },
  body: JSON.stringify({
    mode: "single",
    channel: {
      name: "OpenAI渠道",
      type: 1,
      key: "`<YOUR_API_KEY>`",
      base_url: "https://api.openai.com",
      models: "gpt-3.5-turbo,gpt-4,claude-3-sonnet",
      groups: ["default"],
      priority: 10,
      weight: 100
    }
  })
});
const data = await response.json();

✅ 成功响应示例：

{
  "success": true,
  "message": ""
}

❗ 失败响应示例：

{
  "success": false,
  "message": "不支持的添加模式"
}

🧾 字段说明：

mode （字符串）: 添加模式，可选值："single"、"batch"、"multi_to_single"
multi_key_mode （字符串）: 多密钥模式，当 mode 为"multi_to_single"时必填
channel （对象）: 渠道配置信息
- name （字符串）: 渠道名称
- type （数字）: 渠道类型
- key （字符串）: API 密钥
- base_url （字符串）: 基础 URL
- models （字符串）: 支持的模型列表，逗号分隔，可选
- groups （数组）: 可用分组列表
- priority （数字）: 优先级
- weight （数字）: 权重

更新渠道

接口名称：更新渠道
HTTP 方法：PUT
路径：/api/channel/
鉴权要求：管理员
功能简介：更新现有渠道的配置信息

💡 请求示例：

const response = await fetch('/api/channel/', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  },
  body: JSON.stringify({
    id: 123,
    name: "更新的OpenAI渠道",
    status: 1,
    priority: 15,
    weight: 120
  })
});
const data = await response.json();

✅ 成功响应示例：

{
  "success": true,
  "message": ""
}

❗ 失败响应示例：

{
  "success": false,
  "message": "渠道不存在"
}

🧾 字段说明：

id （数字）: 渠道 ID，必填
其他字段与新增渠道接口相同，均为可选

删除已禁用渠道

接口名称：删除已禁用渠道
HTTP 方法：DELETE
路径：/api/channel/disabled
鉴权要求：管理员
功能简介：批量删除所有已禁用的渠道

💡 请求示例：

const response = await fetch('/api/channel/disabled', {
  method: 'DELETE',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  }
});
const data = await response.json();

✅ 成功响应示例：

{
  "success": true,
  "message": "",
  "data": 5
}

❗ 失败响应示例：

{
  "success": false,
  "message": "删除失败"
}

🧾 字段说明：

无请求参数
data （数字）: 删除的渠道数量

批量禁用标签渠道

接口名称：批量禁用标签渠道
HTTP 方法：POST
路径：/api/channel/tag/disabled
鉴权要求：管理员
功能简介：根据标签批量禁用渠道

💡 请求示例：

const response = await fetch('/api/channel/tag/disabled', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  },
  body: JSON.stringify({
    tag: "test-tag"
  })
});
const data = await response.json();

✅ 成功响应示例：

{
  "success": true,
  "message": ""
}

❗ 失败响应示例：

{
  "success": false,
  "message": "参数错误"
}

🧾 字段说明：

tag （字符串）: 要禁用的渠道标签，必填

批量启用标签渠道

接口名称：批量启用标签渠道
HTTP 方法：POST
路径：/api/channel/tag/enabled
鉴权要求：管理员
功能简介：根据标签批量启用渠道

💡 请求示例：

const response = await fetch('/api/channel/tag/enabled', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  },
  body: JSON.stringify({
    tag: "production-tag"
  })
});
const data = await response.json();

✅ 成功响应示例：

{
  "success": true,
  "message": ""
}

❗ 失败响应示例：

{
  "success": false,
  "message": "参数错误"
}

🧾 字段说明：

tag （字符串）: 要启用的渠道标签，必填

编辑渠道标签

接口名称：编辑渠道标签
HTTP 方法：PUT
路径：/api/channel/tag
鉴权要求：管理员
功能简介：批量编辑指定标签的渠道属性

💡 请求示例：

const response = await fetch('/api/channel/tag', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  },
  body: JSON.stringify({
    tag: "old-tag",
    new_tag: "new-tag",
    priority: 20,
    weight: 150,
    models: "gpt-3.5-turbo,gpt-4,claude-3-sonnet",
    groups: "default,vip"
  })
});
const data = await response.json();

✅ 成功响应示例：

{
  "success": true,
  "message": ""
}

❗ 失败响应示例：

{
  "success": false,
  "message": "tag不能为空"
}

🧾 字段说明：

tag （字符串）: 要编辑的标签名称，必填
new_tag （字符串）: 新标签名称，可选
priority （数字）: 新优先级，可选
weight （数字）: 新权重，可选
model_mapping （字符串）: 模型映射配置，可选
models （字符串）: 支持的模型列表，逗号分隔，可选
groups （字符串）: 可用分组列表，逗号分隔，可选

删除渠道

接口名称：删除渠道
HTTP 方法：DELETE
路径：/api/channel/:id
鉴权要求：管理员
功能简介：硬删除指定渠道，删除后会刷新渠道缓存

💡 请求示例：

const response = await fetch('/api/channel/123', {
  method: 'DELETE',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  }
});
const data = await response.json();

✅ 成功响应示例：

{
  "success": true,
  "message": ""
}

❗ 失败响应示例：

{
  "success": false,
  "message": "渠道不存在"
}

🧾 字段说明：

id （数字）: 渠道 ID，通过 URL 路径传递

批量删除渠道

接口名称：批量删除渠道
HTTP 方法：POST
路径：/api/channel/batch
鉴权要求：管理员
功能简介：根据 ID 列表列表批量删除渠道

💡 请求示例：

const response = await fetch('/api/channel/batch', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  },
  body: JSON.stringify({
    ids: [1, 2, 3, 4, 5]
  })
});
const data = await response.json();

✅ 成功响应示例：

{
  "success": true,
  "message": "",
  "data": 5
}

❗ 失败响应示例：

{
  "success": false,
  "message": "参数错误"
}

🧾 字段说明：

ids （数组）: 要删除的渠道 ID 列表，必填且不能为空
data （数字）: 成功删除的渠道数量

修复渠道能力表

接口名称：修复渠道能力表
HTTP 方法：POST
路径：/api/channel/fix
鉴权要求：管理员
功能简介：修复渠道能力表数据，重新构建渠道与模型的映射关系

💡 请求示例：

const response = await fetch('/api/channel/fix', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  }
});
const data = await response.json();

✅ 成功响应示例：

{
  "success": true,
  "message": "",
  "data": {
    "success": 45,
    "fails": 2
  }
}

❗ 失败响应示例：

{
  "success": false,
  "message": "修复能力表失败"
}

🧾 字段说明：

无请求参数
data.success （数字）: 成功修复的渠道数量
data.fails （数字）: 修复失败的渠道数量

拉取单渠道模型

接口名称：拉取单渠道模型
HTTP 方法：GET
路径：/api/channel/fetch_models/:id
鉴权要求：管理员
功能简介：从指定渠道的上游 API 获取可用模型列表

💡 请求示例：

const response = await fetch('/api/channel/fetch_models/123', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  }
});
const data = await response.json();

✅ 成功响应示例：

{
  "success": true,
  "message": "",
  "data": [
    "gpt-3.5-turbo",
    "gpt-4",
    "gpt-4-turbo-preview"
  ]
}

❗ 失败响应示例：

{
  "success": false,
  "message": "解析响应失败: invalid character 'H' looking for beginning of value"
}

🧾 字段说明：

id （数字）: 渠道 ID，通过 URL 路径传递
data （数组）: 从上游获取的模型 ID 列表

拉取全部渠道模型

接口名称：拉取全部渠道模型
HTTP 方法：POST
路径：/api/channel/fetch_models
鉴权要求：管理员
功能简介：通过提供的配置信息从上游 API获取 API 获取模型列表，用于新建渠道时预览

💡 请求示例：

const response = await fetch('/api/channel/fetch_models', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  },
  body: JSON.stringify({
    base_url: "https://api.openai.com",
    type: 1,
    key: "`<YOUR_API_KEY>`"
  })
});
const data = await response.json();

✅ 成功响应示例：

{
  "success": true,
  "data": [
    "gpt-3.5-turbo",
    "gpt-4",
    "text-davinci-003"
  ]
}

❗ 失败响应示例：

{
  "success": false,
  "message": "Failed to fetch models"
}

🧾 字段说明：

base_url （字符串）: 基础 URL，可选，为空时使用默认 URL
type （数字）: 渠道类型，必填
key （字符串）: API 密钥，必填
data （数组）: 获取到的模型列表

批量设置渠道标签

接口名称：批量设置渠道标签
HTTP 方法：POST
路径：/api/channel/batch/tag
鉴权要求：管理员
功能简介：为指定的渠道列表批量设置标签

💡 请求示例：

const response = await fetch('/api/channel/batch/tag', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  },
  body: JSON.stringify({
    ids: [1, 2, 3],
    tag: "production"
  })
});
const data = await response.json();

✅ 成功响应示例：

{
  "success": true,
  "message": "",
  "data": 3
}

❗ 失败响应示例：

{
  "success": false,
  "message": "参数错误"
}

🧾 字段说明：

ids （数组）: 要设置标签的渠道 ID 列表，必填且不能为空
tag （字符串）: 要设置的标签名称，传 null 可清除标签
data （数字）: 成功设置标签的渠道数量

根据标签获取模型

接口名称：根据标签获取模型
HTTP 方法：GET
路径：/api/channel/tag/models
鉴权要求：管理员
功能简介：获取指定标签下所有渠道中模型数量最多的模型列表

💡 请求示例：

const response = await fetch('/api/channel/tag/models?tag=production', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  }
});
const data = await response.json();

✅ 成功响应示例：

{
  "success": true,
  "message": "",
  "data": "gpt-3.5-turbo,gpt-4,claude-3-sonnet"
}

❗ 失败响应示例：

{
  "success": false,
  "message": "tag不能为空"
}

🧾 字段说明：

tag （字符串）: 标签名称，必填
data （字符串）: 该标签下模型最多的渠道的模型列表，逗号分隔

复制渠道

接口名称：复制渠道
HTTP 方法：POST
路径：/api/channel/copy/:id
鉴权要求：管理员
功能简介：复制现有渠道创建新渠道，支持自定义后缀和余额重置选项

💡 请求示例：

const response = await fetch('/api/channel/copy/123?suffix=_备份&reset_balance=true', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  }
});
const data = await response.json();

✅ 成功响应示例：

{
  "success": true,
  "message": "",
  "data": {
    "id": 124
  }
}

❗ 失败响应示例：

{
  "success": false,
  "message": "invalid id"
}

🧾 字段说明：

id （数字）: 要复制的渠道 ID，通过 URL 路径传递
suffix （字符串）: 可选，添加到原名称后的后缀，默认为"_复制"
reset_balance （布尔型）: 可选，是否重置余额和已用配额为 0，默认为 true
data.id （数字）: 新创建的渠道 ID

目录