自定义 LLM API

在 Convai 上管理你的私有 LLM 集成。通过简单的 API 端点安全地注册、更新或删除与 OpenAI 兼容的自定义模型。

自定义 LLM 集成仅适用于企业版套餐。

简介

该 Convai 自定义 LLM 模型 API 允许开发者和企业注册并管理他们自己的 自定义大语言模型（LLM） 在 Convai 平台上。 通过这些端点，您可以连接私有的、与 OpenAI 兼容的 LLM，控制访问，并管理注册、更新和移除等生命周期事件。

所有端点均为 POST 请求，并且都接收和返回 JSON 对象。

---

基础 URL

https://api.convai.com

---

身份验证

每个请求都必须在标头中包含您的 Convai API 密钥。没有它，请求将返回 401 未经授权.

标头	描述	示例
CONVAI-API-KEY	每个请求都必需	245a4u6864dj6848516l2dr6df

缺少密钥或密钥无效时的示例错误：

{
  "status": "error",
  "message": "未经授权：缺少或无效的 CONVAI-API-KEY",
  "transactionID": "..."
}

---

通用响应字段

所有端点在响应中都共享以下基础结构。

字段	类型	描述
status	字符串	"success" 或 "error"
message	字符串	人类可读摘要
transactionID	字符串	用于跟踪的唯一标识符
...	—	端点特定数据

---

端点参考

#	方法与路径	用途
2.1 注册模型	POST /llm-models/register	注册一个新的自定义模型
2.2 更新模型	POST /llm-models/update	更新现有的自定义模型
2.3 注销模型	POST /llm-models/deregister	移除已注册的模型
2.4 列出模型	POST /llm-models/list	列出与您的 API 密钥关联的所有自定义模型

---

2.1 注册模型

端点：

POST https://api.convai.com/llm-models/register

请求正文

字段	类型	必需	说明
model_group_name	字符串	✓	唯一且不可变的标识符
model_name	字符串	✓	模型名称，例如 "gpt-4o-mini"
api_key	字符串	✓	远程 LLM 端点的密钥
is_uncensored	布尔值	✓	如果无越狱限制则为 True
display_name	字符串	—	可选的 UI 标签（默认为组名）
base_url	字符串	—	与 OpenAI 兼容的端点（默认： https://api.openai.com/v1)

示例 cURL

MacOS/Linux

curl -X POST https://api.convai.com/llm-models/register \
  -H "Content-Type: application/json" \
  -H "CONVAI-API-KEY: YOUR_API_KEY" \
  -d '{
        "model_group_name": "my-turbo",
        "model_name": "gpt-4o-mini",
        "api_key": "sk-proxy-123",
        "is_uncensored": false,
        "display_name": "Turbo（私有）",
        "base_url": "https://api.openai.com/v1"
      }'

Windows

成功响应（200 OK）

{
  "status": "success",
  "model_group_name": "my-turbo",
  "model_name": "gpt-4o-mini",
  "display_name": "Turbo（私有）",
  "message": "模型 'my-turbo' 注册成功",
  "transactionID": "14b0cf96-5230-4b0f-a971-2f4f4f6d5e6a"
}

可能的错误

代码	消息	原因
400	缺少必填字段	验证失败
409	模型组名称已存在	重复标识符
500	数据库错误	内部服务器错误

---

2.2 更新模型

端点：

POST https://api.convai.com/llm-models/update

请求正文

字段	类型	必需	说明
model_group_name	字符串	✓	要更新的模型
display_name	字符串	—	新的友好名称
base_url	字符串	—	更新后的端点 URL
api_key	字符串	—	新的 API 密钥
is_uncensored	布尔值	—	切换审查

至少需要一个可选字段。

示例 cURL

MacOS/Linux

curl -X POST https://api.convai.com/llm-models/update \
  -H "Content-Type: application/json" \
  -H "CONVAI-API-KEY: YOUR_API_KEY" \
  -d '{
        "model_group_name": "my-turbo",
        "display_name": "Turbo v2",
        "api_key": "sk-proxy-456"
      }'

Windows

成功响应（200 OK）

{
  "status": "success",
  "message": "模型 'my-turbo' 更新成功",
  "updated_fields": ["display_name", "api_key"],
  "transactionID": "5c0b6c67-97e4-4d78-9d5c-2a3de9d9c8ee"
}

可能的错误

代码	消息	原因
404	未找到模型	模型名称无效或未获授权
409	显示名称已存在	重复用户标签
400	没有可更新的有效字段	缺少可更新字段

---

2.3 注销模型

端点：

POST https://api.convai.com/llm-models/deregister

请求正文

字段	类型	必需
model_group_name	字符串	✓

示例 cURL

MacOS/Linux

curl -X POST https://api.convai.com/llm-models/deregister \
  -H "Content-Type: application/json" \
  -H "CONVAI-API-KEY: YOUR_API_KEY" \
  -d '{ "model_group_name": "my-turbo" }'

Windows

成功响应（200 OK）

{
  "status": "success",
  "message": "模型 'my-turbo' 注销成功",
  "transactionID": "b11ac4f7-4cd3-4f43-8a79-3c942a14a8c9"
}

可能的错误

代码	消息	原因
404	未找到模型	模型不存在，或不归请求者所有

---

2.4 列出模型

端点：

POST https://api.convai.com/llm-models/list

此端点不需要请求正文。

示例 cURL

MacOS/Linux

curl -X POST https://api.convai.com/llm-models/list \
  -H "Content-Type: application/json" \
  -H "CONVAI-API-KEY: YOUR_API_KEY"

Windows

成功响应（200 OK）

{
  "status": "success",
  "models": [
    {
      "model_group_name": "my-turbo",
      "model_name": "gpt-4o-mini",
      "display_name": "Turbo（私有）",
      "base_url": "https://api.openai.com/v1",
      "is_uncensored": false,
      "category": "Private",
      "created_at": "2025-07-08T09:41:38.123Z"
    },
    {
      "model_group_name": "raw-mixtral",
      "model_name": "mixtral-8x22b-base",
      "display_name": "Mixtral 原始版",
      "base_url": "https://llm.my-org.net/v1",
      "is_uncensored": true,
      "category": "Private",
      "created_at": "2025-05-21T14:02:05.551Z"
    }
  ],
  "count": 2,
  "transactionID": "2caa4b99-eda9-46e2-a9ee-b4f251afcb1f"
}

---

3. 错误参考（所有端点）

HTTP 代码	典型原因
400	参数缺失或格式错误
401	API 密钥无效或缺失
404	模型未找到或不属于用户
409	组名或显示名称重复
429	超出速率限制
500	内部服务器错误

错误示例：

{
  "status": "error",
  "message": "未找到模型 'x' 或访问被拒绝",
  "transactionID": "..."
}

---

4. 使用说明与最佳实践

Convai 目前仅支持 与 OpenAI 兼容的端点。 大多数主流提供商（OpenAI、Google、Cohere、Hugging Face、vLLM、SGLang）都支持这种格式。

model_group_name 为 不可变的；请谨慎选择（例如 llama3.1-70b-companyX ，而不是通用名称）。

display_name 值必须 每个用户唯一.

在使用 注销 某个模型之前，请确保所有正在使用该模型的角色都已切换到其他模型，否则它们将无法工作。

---

结论

该 自定义 LLM API 提供了一种简化的方式，可在 Convai 中集成、管理和控制自定义 LLM 端点。 通过维护唯一标识符、安全的 API 密钥以及与 OpenAI 兼容的 URL，您可以确保面向用例的稳定且私密的模型部署。