渠道管理模組

功能說明

介面字首統一為 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

目錄