> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/character-crafting-apis/custom-llm-api.md). # 自定义 LLM API {% hint style="danger" %} 自定义 LLM 集成仅适用于企业版套餐。 {% endhint %} ## 简介 该 **Convai 自定义 LLM 模型 API** 允许开发者和企业注册并管理他们自己的 **自定义大语言模型（LLM）** 在 Convai 平台上。\ 通过这些端点，您可以连接私有的、与 OpenAI 兼容的 LLM，控制访问，并管理注册、更新和移除等生命周期事件。 所有端点均为 **POST** 请求，并且都接收和返回 **JSON** 对象。 {% embed url="" %} *** ## 基础 URL ``` https://api.convai.com ``` *** ## 身份验证 每个请求都必须在标头中包含您的 Convai API 密钥。没有它，请求将返回 **401 未经授权**. | 标头 | 描述 | 示例 | | ------------------ | ------- | ---------------------------- | | **CONVAI-API-KEY** | 每个请求都必需 | `245a4u6864dj6848516l2dr6df` | 缺少密钥或密钥无效时的示例错误： ```json { "status": "error", "message": "未经授权：缺少或无效的 CONVAI-API-KEY", "transactionID": "..." } ``` *** ## 通用响应字段 所有端点在响应中都共享以下基础结构。 | 字段 | 类型 | 描述 | | ----------------- | :-: | :-----------------: | | **status** | 字符串 | "success" 或 "error" | | **message** | 字符串 | 人类可读摘要 | | **transactionID** | 字符串 | 用于跟踪的唯一标识符 | | **...** | — | 端点特定数据 | *** ## 端点参考 | # | 方法与路径 | 用途 | | ---------------------------------------- | ----------------------------- | ---------------------- | | [**2.1 注册模型**](#id-2.1-register-a-model) | `POST /llm-models/register` | 注册一个新的自定义模型 | | [**2.2 更新模型**](#id-2.2-update-a-model) | `POST /llm-models/update` | 更新现有的自定义模型 | | [**2.3 注销模型**](#id-2.2-update-a-model) | `POST /llm-models/deregister` | 移除已注册的模型 | | [**2.4 列出模型**](#id-2.4-list-models) | `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 {% tabs %} {% tab title="MacOS/Linux" %} ```bash 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" }' ``` {% endtab %} {% tab title="Windows" %} {% code overflow="wrap" %} ```powershell 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\"}" ``` {% endcode %} {% endtab %} {% endtabs %} #### 成功响应（200 OK） ```json { "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 {% tabs %} {% tab title="MacOS/Linux" %} ```bash 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" }' ``` {% endtab %} {% tab title="Windows" %} {% code overflow="wrap" %} ```powershell 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\"}" ``` {% endcode %} {% endtab %} {% endtabs %} #### 成功响应（200 OK） ```json { "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 {% tabs %} {% tab title="MacOS/Linux" %} ```bash 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" }' ``` {% endtab %} {% tab title="Windows" %} {% code overflow="wrap" %} ```powershell 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\"}" ``` {% endcode %} {% endtab %} {% endtabs %} #### 成功响应（200 OK） ```json { "status": "success", "message": "模型 'my-turbo' 注销成功", "transactionID": "b11ac4f7-4cd3-4f43-8a79-3c942a14a8c9" } ``` #### 可能的错误 | 代码 | 消息 | 原因 | | --- | ----- | -------------- | | 404 | 未找到模型 | 模型不存在，或不归请求者所有 | *** ### 2.4 列出模型 **端点：** `POST` `https://api.convai.com/llm-models/list` 此端点不需要请求正文。 #### 示例 cURL {% tabs %} {% tab title="MacOS/Linux" %} ```bash curl -X POST https://api.convai.com/llm-models/list \ -H "Content-Type: application/json" \ -H "CONVAI-API-KEY: YOUR_API_KEY" ``` {% endtab %} {% tab title="Windows" %} {% code overflow="wrap" %} ```powershell curl -X POST "https://api.convai.com/llm-models/list" -H "Content-Type: application/json" -H "CONVAI-API-KEY: YOUR_API_KEY" ``` {% endcode %} {% endtab %} {% endtabs %} #### 成功响应（200 OK） ```json { "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** | 内部服务器错误 | 错误示例： ```json { "status": "error", "message": "未找到模型 'x' 或访问被拒绝", "transactionID": "..." } ``` *** ## 4. 使用说明与最佳实践 {% hint style="danger" %} Convai 目前仅支持 **与 OpenAI 兼容的端点**。\ 大多数主流提供商（OpenAI、Google、Cohere、Hugging Face、vLLM、SGLang）都支持这种格式。 {% endhint %} {% hint style="warning" %} **model\_group\_name** 为 **不可变的**；请谨慎选择（例如 `llama3.1-70b-companyX` ，而不是通用名称）。 {% endhint %} {% hint style="warning" %} **display\_name** 值必须 **每个用户唯一**. {% endhint %} {% hint style="warning" %} 在使用 **注销** 某个模型之前，请确保所有正在使用该模型的角色都已切换到其他模型，否则它们将无法工作。 {% endhint %} *** ## 结论 该 **自定义 LLM API** 提供了一种简化的方式，可在 Convai 中集成、管理和控制自定义 LLM 端点。\ 通过维护唯一标识符、安全的 API 密钥以及与 OpenAI 兼容的 URL，您可以确保面向用例的稳定且私密的模型部署。 --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/character-crafting-apis/custom-llm-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.