> 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/convai-playground/character-customization/external-api/external-api-limitations.md).

# 外部 API 限制

适用于整个外部 API 的限制——支持的模型、Python 运行时、库、输入模式以及每个角色的上限。

无论你是在以下位置配置 External API，这些限制都适用 [演练场](/api-docs/zh/convai-playground/character-customization/external-api.md) 或通过 [API](/api-docs/zh/api-can-kao/core-api-reference/character-crafting-apis/external-api.md).

## 支持的模型

只有当角色的模型能够调用工具时，External API 才会运行。这取决于你使用的路径：

| 路径                 | 支持的模型                                                                                                                      |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| **实时 API（WebRTC）** | OpenAI、Claude 和 Gemini。支持工具的流行开源模型——包括 Grok 和 DeepSeek 系列——在这里也能使用。其他模型如果支持工具调用也可能可用；请查看 [models.dev](https://models.dev). |
| **gRPC**           | 仅限 OpenAI、Claude 和 Gemini 系列模型。                                                                                            |

如果模型不支持工具，角色仍然会正常聊天——只是不会调用你的 External API 函数。

## 运行时

| 规则    | 详情                                                       |
| ----- | -------------------------------------------------------- |
| 语言    | 仅限 Python（`"language": "python"`)                        |
| 运行时   | Python 3.11                                              |
| 标准库   | 允许（`json`, `datetime`, `math`, `re`, `urllib`以及标准库的其余部分） |
| 第三方包  | **`requests` 仅** 暂时                                      |
| 源代码大小 | 最多 400 行                                                 |
| 入口点   | 必须定义 `def handle_event(inputs):` （单个参数；名称固定）             |
| 返回值   | 可 JSON 序列化，通常是一个 `dict`                                  |
| State | 调用之间没有共享的可变状态——每次运行都是独立的                                 |

标准库之外的任何内容以及 `requests` 都会在运行时失败。

## 输入说明

`input_description` 是一个 **JSON 字符串** （不是 API 请求体中的嵌套对象）。解析后，它必须看起来像：

```json
{
  "parameters": {
    "city": {
      "type": "string",
      "description": "要查询的城市名称"
    }
  },
  "required": ["city"]
}
```

| 规则                  | 详情                                            |
| ------------------- | --------------------------------------------- |
| 顶层键                 | `parameters` 和 `必填` 二者都是必需的                   |
| 参数名称                | `^[a-zA-Z_][a-zA-Z0-9_]*$`                    |
| 参数字段                | 每个参数都需要 `type` 和 `描述`                         |
| 允许的类型               | `string`, `integer`, `布尔值`, `object`, `array` |
| 下方的额外键 `parameters` | 不允许                                           |

保持描述具体。模型会根据这段文本填充参数，因此含糊的措辞会导致错误的调用。

## 字符限制

| 规则          | 详情                                                      |
| ----------- | ------------------------------------------------------- |
| 每个角色的已启用函数数 | 最多 **128**                                              |
| 取消关联 vs 删除  | `"status": "inactive"` 只会解除某个角色的关联；删除会将该函数从账户中以及所有关联中移除 |

## 相关

* [External API（Playground）](/api-docs/zh/convai-playground/character-customization/external-api.md) — 界面设置和示例
* [External API（API 参考）](/api-docs/zh/api-can-kao/core-api-reference/character-crafting-apis/external-api.md) — 创建、列出、关联、取消关联、删除


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/convai-playground/character-customization/external-api/external-api-limitations.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.