> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitheo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 自定义提供方

> 注册、列出并删除你自己的 OpenAI 兼容模型端点(自带模型)。

将任意 **OpenAI 兼容**的 chat-completions 端点注册为自定义提供方,然后即可在[模型方案](/api-reference/keys/model-plan)或[编排器图](/api-reference/keys/orchestrator-graph)的 Model 节点中,通过带命名空间的 id `custom:<providerId>:<modelId>` 引用其模型。发往你自己模型的请求是**免费**的,不会消耗 Theo 令牌——你直接向你的提供方付费。

## 身份验证

需要具备 `billing` 权限范围的 API 密钥。

## 注册一个提供方

`POST /api/v1/custom-providers`

<ParamField body="name" type="string" required>显示名称(1–120 个字符)。</ParamField>
<ParamField body="base_url" type="string" required>该端点的基础 URL——必须是 `http(s)`。</ParamField>
<ParamField body="api_key" type="string" required>提供方的 API 密钥。以加密方式存储;API 永远不会返回该值。</ParamField>

<ParamField body="models" type="object[]" required>
  1–50 个模型。每个模型:`{ id, label, contextWindow? }`。

  <Expandable title="model fields">
    <ParamField body="id" type="string" required>发送给你端点的原始模型 id(1–200 个字符)。</ParamField>
    <ParamField body="label" type="string" required>显示标签(1–120 个字符)。</ParamField>

    <ParamField body="contextWindow" type="integer">
      可选的声明式上下文窗口大小(以令牌计)。设置后,Theo 的上下文窗口护栏可以在超大请求发往你的端点**之前**将其拦截(并在该密钥上存在更大模型可用时,将请求绕道路由过去)。若未知可省略——此时该模型会被视为无上限,直接放行通过护栏。
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="local" type="boolean">
  本机 / 本地部署:仅可从已关联的桌面端访问,永不从云端派发。默认值为 `false`。
</ParamField>

返回 `{ id }`——即该提供方的 id。可通过 `custom:<id>:<modelId>` 引用其模型。

## 列出提供方

`GET /api/v1/custom-providers` → `{ providers: [{ id, name, base_url, models }] }`。API 密钥永远不会包含在返回结果中。

## 删除一个提供方

`DELETE /api/v1/custom-providers/{id}` → `{ deleted: true }`。

## 示例

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://www.hitheo.ai/api/v1/custom-providers \
    -H "Authorization: Bearer $THEO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "My vLLM",
      "base_url": "https://llm.example.com/v1",
      "api_key": "sk-...",
      "models": [{ "id": "my-llama-70b", "label": "Llama 70B", "contextWindow": 131072 }]
    }'
  ```
</CodeGroup>

然后将其固定到某个密钥上:

```ts theme={null}
await theo.keys.setModelPlan("KEY_ID", {
  single_model: { upstream_id: "custom:PROVIDER_ID:my-llama-70b" },
});
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.