agentbase-docs

LLM Gateway API

面向项目的 LLM 网关数据面与管理面:OpenAI 兼容 chat/completions 与 embeddings、Anthropic Messages 兼容 messages、rerank;上游 provider(openai / anthropic / dashscope / theta)连接、模型清单、健康检查、网关子密钥与平台试用 provider 绑定。

资源与基础路径

认证与权限

认证与请求头约定见 通用约定。scope 四类:

数据面限流独立于普通管理面:chat / messages / rerank 每分钟 60 次,embeddings 每分钟 120 次。provider 开启 allowByok 时,调用方可带 X-Provider-Key 头自带上游 API Key(BYOK)。

端点清单

方法 + 路径用途
POST /llm-gateway/chat/completionsChat Completions(OpenAI 兼容)
POST /llm-gateway/messagesMessages(Anthropic 兼容)
POST /llm-gateway/embeddings文本向量化
POST /llm-gateway/rerank文档重排
GET /llm-gateway/models / GET .../models/{modelId}可用模型列表/详情
`GETPOST /llm-gateway/providers、GETPATCHDELETE .../providers/{providerId}`provider CRUD
GET .../providers/{providerId}/healthprovider 健康
POST .../providers/{providerId}/health-checks校验 provider 全部已配模型
GET .../providers/{providerId}/models上游实际可用模型
POST .../providers/cache/refresh刷新 provider 缓存
POST /llm-gateway/provider-model-discoveries发现并分类 DashScope 凭证可用模型
`GETPOST /llm-gateway/keys、PATCHDELETE .../keys/{keyId}`网关子密钥管理
`GETPOST /llm-gateway/trial-provider-bindings、GETDELETE .../trial-provider-bindings/{bindingId}、POST .../{bindingId}/health-checks`平台试用 provider 绑定与绑定健康检查
GET /llm-gateway/trial-providers可绑定的平台试用 provider 清单

请求与响应

以下按端点给出完整规格:输入(path / query / body 字段级表格)、输出(返回模型与关键字段)、调用示例(可复制的 curl)与响应示例。标注「泛化 schema any」的端点,响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准。

数据面

POST /v1/llm-gateway/chat/completions

以 OpenAI Chat Completions 兼容格式创建对话补全:网关按请求体 model 路由到活跃 Provider,透传原生消息字段,记录项目 / 模型 / 网关子密钥三级用量。

输入:

参数位置类型必填默认/枚举说明
modelbodystring是—用于补全的模型 ID,必须与某活跃 Provider 的模型清单精确匹配(不支持 provider/model 前缀)。
messagesbodyobject[]是—上游原生对话消息数组,字段原样透传:文本、多模态(content 为分段数组)与 tool-calling(role: tool、tool_calls)均支持。
temperaturebodynumber否—采样温度,0–2,缺省用上游默认值。
maxTokensbodyinteger否—最大生成 token 数。
streambodyboolean否—是否以 SSE 流式返回;true 时响应为 text/event-stream 分片(chat.completion.chunk)。
toolsbodyobject[]否—OpenAI 兼容的工具定义数组(type: function + function.{name,parameters}),透传给上游。
tool_choicebodyobject否—工具选择策略:"auto" / "none" 或 {"type":"function","function":{"name":"..."}} 强制指定。

输出:返回上游原生补全(经网关透传):非流式为完整 chat.completion JSON(含 choices[].message 与 usage 计量字段);stream=true 时为 SSE 分片序列。用量按 UTC 日归集到项目 / 模型 / 子密钥三级。

调用示例:

curl -X POST "https://<your-endpoint>/v1/llm-gateway/chat/completions" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      { "role": "system", "content": "你是一个简洁的中文助手。" },
      { "role": "user", "content": "用一句话介绍 TablesDB。" }
    ],
    "temperature": 0.7,
    "maxTokens": 1024,
    "stream": false
  }'
# 流式:将 stream 设为 true,响应为 SSE(data: {"choices":[{"delta":{...}}]} 分片,以 data: [DONE] 结束)

响应示例:

{
  "id": "chatcmpl-8f2a9c1d",
  "object": "chat.completion",
  "created": 1757491200,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "TablesDB 是 Agentbase 提供的结构化表格存储服务,支持行级权限与事务。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 33,
    "total_tokens": 61
  }
}

POST /v1/llm-gateway/messages

以 Anthropic Messages 兼容格式创建消息:路由时优先选择 anthropic 类型 Provider,必要时回退通用模型路由,返回 Anthropic Messages 结构。

输入:

参数位置类型必填默认/枚举说明
modelbodystring是—目标模型 ID;anthropic 模型优先路由到 anthropic Provider。
messagesbodyobject[]是—Anthropic 原生消息数组(`role: user\assistant,content` 为字符串或分段数组),原样透传。
maxTokensbodyinteger是—最大生成 token 数,必填;不传时网关按 1024 处理。
systembodystring否—系统提示词;网关将其前插为 system 消息后再透传。
temperaturebodynumber否—采样温度,0–1。
streambodyboolean否—是否以 SSE 流式返回分片。

输出:返回 Anthropic Messages 兼容结构:content[](type: text 等分段)、stop_reason、usage(input_tokens / output_tokens);流式时为 SSE 分片。

调用示例:

curl -X POST "https://<your-endpoint>/v1/llm-gateway/messages" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-5-sonnet-20241022",
    "maxTokens": 1024,
    "system": "你是客服质检助手,只输出 JSON。",
    "messages": [
      { "role": "user", "content": "检查这条回复是否包含承诺赔付的表述。" }
    ],
    "temperature": 0.5,
    "stream": false
  }'
# Gateway Key 认证:Authorization: Bearer abk_... (可省略 X-Appwrite-Project)

响应示例:

{
  "id": "msg_01XFDUDYJgAACzvnptvVoaEL",
  "type": "message",
  "role": "assistant",
  "model": "claude-3-5-sonnet-20241022",
  "content": [
    {
      "type": "text",
      "text": "{\"contains_compensation\": false, \"confidence\": 0.92}"
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 42,
    "output_tokens": 28
  }
}

POST /v1/llm-gateway/embeddings

对一批文本生成向量:按 embedding 模型 ID 路由到活跃 Provider,返回 OpenAI 兼容的向量数组与 token 用量。不支持流式。

输入:

参数位置类型必填默认/枚举说明
modelbodystring是—embedding 模型 ID,须在 Provider 的 embeddingModels 中。
inputbodystring[]是—输入文本数组,每个元素生成一条向量;结果 data[].index 与数组顺序对应。

输出:返回 llmGatewayEmbeddingResponse:

字段类型说明
objectstring对象类型,恒为 list(OpenAI 兼容字段)。
modelstring实际生成向量的模型。
dataobject[]向量对象数组,每项含 object、index 与 embedding 浮点数组,顺序与 input 一一对应。
usageobjecttoken 用量:prompt_tokens / total_tokens。

调用示例:

curl -X POST "https://<your-endpoint>/v1/llm-gateway/embeddings" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": [
      "Agentbase 是一个 BaaS 平台",
      "TablesDB 提供结构化数据存储"
    ]
  }'

响应示例:

{
  "object": "list",
  "model": "text-embedding-3-small",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        0.0023,
        -0.0091,
        0.0154
      ]
    },
    {
      "object": "embedding",
      "index": 1,
      "embedding": [
        0.0031,
        -0.0087,
        0.0149
      ]
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "total_tokens": 24
  }
}

POST /v1/llm-gateway/rerank

按查询相关性对候选文档重排:返回按相关性降序的输入下标与得分,可选携带文档原文。不支持流式。

输入:

参数位置类型必填默认/枚举说明
modelbodystring是—rerank 模型 ID,须在 Provider 的 rerankModels 中。
querybodystring是—用于相关性判定的查询文本。
documentsbodystring[]是—候选文档文本数组;返回结果中的 index 指向该数组的下标。
topNbodyinteger否—只返回前 N 条结果。
returnDocumentsbodyboolean否—是否在结果中附带文档原文(document 字段)。

输出:返回 llmGatewayRerankResponse:

字段类型说明
modelstring执行重排的模型。
resultsobject[]按相关性降序的结果数组,每项含 index(输入 documents 下标)与 relevance_score(0–1);returnDocuments=true 时附带 document 原文。
usageobjecttoken 用量:total_tokens。

调用示例:

curl -X POST "https://<your-endpoint>/v1/llm-gateway/rerank" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gte-rerank",
    "query": "如何创建 Agentbase 用户",
    "documents": [
      "使用 Account API 创建邮箱密码用户。",
      "TablesDB 提供结构化数据存储。"
    ],
    "topN": 2,
    "returnDocuments": false
  }'

响应示例:

{
  "model": "gte-rerank",
  "results": [
    {
      "index": 0,
      "relevance_score": 0.97
    },
    {
      "index": 1,
      "relevance_score": 0.31
    }
  ],
  "usage": {
    "total_tokens": 45
  }
}

GET /v1/llm-gateway/models

列出项目内当前可路由的全部模型:对各活跃 Provider 的 chatModels / embeddingModels / rerankModels / vlmModels 汇总去重。

输入:无 path/query/body 参数。

输出:返回 llmGatewayModelList(total + models[]),数组元素为 llmGatewayModel:

字段类型说明
$idstring模型 ID(即请求体 model 需要精确匹配的值)。
objectstring对象类型,恒为 model(OpenAI 兼容字段)。
createdinteger上游模型创建时间(Unix 秒)。
ownedBystring归属 Provider(类型或连接标识)。
capabilitiesstring[]支持能力:chat / embedding / rerank / vlm。
activeboolean当前是否可路由(Provider 须为 active)。
sourcestring,可选模型来源:project(项目 Provider)/ platformTrial(平台试用)/ mixed。
sourcesobject[],可选来源安全投影列表。
trialQuotaobject,可选存在平台试用来源时,账号-模型维度的试用配额。

调用示例:

curl "https://<your-endpoint>/v1/llm-gateway/models" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "total": 2,
  "models": [
    {
      "$id": "gpt-4o-mini",
      "object": "model",
      "created": 1721174400,
      "ownedBy": "openai",
      "capabilities": [
        "chat"
      ],
      "active": true,
      "source": "project",
      "sources": [
        "project"
      ]
    },
    {
      "$id": "gte-rerank",
      "object": "model",
      "created": 1719043200,
      "ownedBy": "dashscope",
      "capabilities": [
        "rerank"
      ],
      "active": true,
      "source": "platformTrial",
      "sources": [
        "platformTrial"
      ],
      "trialQuota": {
        "remainingTokens": 480000
      }
    }
  ]
}

GET /v1/llm-gateway/models/{modelId}

读取单个可用模型详情;模型必须被某个活跃 Provider 显式声明或经通配路由命中。

输入:

参数位置类型必填默认/枚举说明
modelIdpathstring是—模型 ID,与列表端点返回的 $id 一致。

输出:返回 llmGatewayModel:

字段类型说明
$idstring模型 ID(即请求体 model 需要精确匹配的值)。
objectstring对象类型,恒为 model(OpenAI 兼容字段)。
createdinteger上游模型创建时间(Unix 秒)。
ownedBystring归属 Provider(类型或连接标识)。
capabilitiesstring[]支持能力:chat / embedding / rerank / vlm。
activeboolean当前是否可路由(Provider 须为 active)。
sourcestring,可选模型来源:project(项目 Provider)/ platformTrial(平台试用)/ mixed。
sourcesobject[],可选来源安全投影列表。
trialQuotaobject,可选存在平台试用来源时,账号-模型维度的试用配额。

调用示例:

curl "https://<your-endpoint>/v1/llm-gateway/models/gpt-4o-mini" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "$id": "gpt-4o-mini",
  "object": "model",
  "created": 1721174400,
  "ownedBy": "openai",
  "capabilities": [
    "chat"
  ],
  "active": true,
  "source": "project",
  "sources": [
    "project"
  ]
}

Provider 管理

GET /v1/llm-gateway/providers

列出项目内全部 Provider 连接:按路由优先级排序,用于检视已配置上游、模型清单、状态与健康度。

输入:无 path/query/body 参数。

输出:返回 llmGatewayProviderList(total + providers[]),元素为 llmGatewayProvider:

字段类型说明
$idstringProvider ID。
$createdAtstring创建时间(ISO 8601)。
$updatedAtstring最近更新时间(ISO 8601)。
connectionNamestring连接名,项目内唯一。
providerTypestring上游类型:openai / anthropic / dashscope / theta。
baseUrlstring上游 API base URL。
apiKeySetboolean是否已配置上游密钥;响应永不回显 apiKey 本体。
defaultModelstring该连接的默认模型。
allowedCapabilitiesstring[]放行能力:chat / embedding / rerank / vlm(由各模型清单派生)。
supportedModelsstring[]兼容字段:全部支持模型 ID 的汇总(服务端派生)。
chatModelsstring[]可用于 chat completions 的模型 ID。
embeddingModelsstring[]可用于 embeddings 的模型 ID。
rerankModelsstring[]可用于 rerank 的模型 ID。
vlmModelsstring[]可用于视觉理解的模型 ID(复用 chat completions 端点)。
descriptionstring连接描述。
statusstring运行状态:active / paused。
isDefaultboolean是否为同类型默认 Provider。
priorityintegerfailover 优先级,数值越小越优先。
timeoutMsinteger上游请求超时(毫秒)。
maxRetriesinteger最大重试次数。
maxInputTokensinteger最大输入 token;null 表示不限。
allowByokboolean是否允许调用方经 X-Provider-Key 头自带上游密钥(BYOK)。
healthStatusstring健康状态:HEALTHY / UNHEALTHY / UNKNOWN。
healthMessagestring最近一次模型校验失败的摘要。
lastValidatedAtstring最近一次健康校验时间。
lastUsedAtstring最近一次被路由使用的时间。
memoryEmbeddingReferencedboolean是否已被项目 Memory embedding 配置引用;null 表示本次响应未评估约束。
immutableFieldsstring[]被 Memory 引用期间不可修改的字段列表。
deleteAllowedboolean当前是否允许删除;null 表示未评估。
credentialPolicystring凭据变更策略:mutable / rotate-only;空表示未评估。

调用示例:

curl "https://<your-endpoint>/v1/llm-gateway/providers" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "total": 1,
  "providers": [
    {
      "$id": "openai-prod",
      "$createdAt": "2026-08-01T03:12:45.231+00:00",
      "$updatedAt": "2026-08-01T03:12:45.231+00:00",
      "connectionName": "openai-production",
      "providerType": "openai",
      "baseUrl": "https://api.openai.com",
      "apiKeySet": true,
      "defaultModel": "gpt-4o-mini",
      "allowedCapabilities": [
        "chat",
        "embedding"
      ],
      "supportedModels": [
        "gpt-4o-mini",
        "text-embedding-3-small"
      ],
      "chatModels": [
        "gpt-4o-mini"
      ],
      "embeddingModels": [
        "text-embedding-3-small"
      ],
      "rerankModels": [],
      "vlmModels": [],
      "description": "生产 OpenAI 连接",
      "status": "active",
      "isDefault": true,
      "priority": 0,
      "timeoutMs": 60000,
      "maxRetries": 3,
      "maxInputTokens": 128000,
      "allowByok": false,
      "healthStatus": "HEALTHY",
      "healthMessage": "",
      "lastValidatedAt": "2026-08-01T03:13:02.884+00:00",
      "lastUsedAt": "2026-09-01T08:00:11.102+00:00",
      "memoryEmbeddingReferenced": false,
      "immutableFields": [],
      "deleteAllowed": true,
      "credentialPolicy": "mutable"
    }
  ]
}

POST /v1/llm-gateway/providers

创建 Provider 连接:推荐用四个能力模型清单声明各能力可用模型,服务端派生 allowedCapabilities 与兼容字段 supportedModels,保存前逐一验证全部模型。

输入:

参数位置类型必填默认/枚举说明
providerIdbodystring是—Provider ID,自定义或 ID.unique()。
connectionNamebodystring是—连接名,项目内唯一,重复创建返回 409。
providerTypebodystring是枚举 openai, anthropic, dashscope, theta上游类型枚举:openai / anthropic / dashscope / theta。
baseUrlbodystring是—上游 API base URL,须为合法 HTTP(S) 地址。
apiKeybodystring否—上游密钥或令牌;加密存储,任何读取端点只回显 apiKeySet,不返回原文。
defaultModelbodystring否—该连接的默认模型。
allowedCapabilitiesbodystring[]否—放行能力数组;通常不传,由四个模型清单派生。
supportedModelsbodystring[]否—兼容旧客户端的字段;与四个清单同传时以清单派生结果为准。不接受 * 通配符。
chatModelsbodystring[]否—chat 能力模型清单;VLM 复用 chat completions 端点,视觉模型登记在 vlmModels。
embeddingModelsbodystring[]否—embedding 能力模型清单。
rerankModelsbodystring[]否—rerank 能力模型清单。
vlmModelsbodystring[]否—视觉语言模型清单。
chatCompletionsPathbodystring否—上游 chat completions 路径覆盖,默认 /v1/chat/completions。
embeddingsPathbodystring否—上游 embeddings 路径覆盖,默认 /v1/embeddings。
rerankPathbodystring否—上游 rerank 路径覆盖;留空表示该 Provider 不支持 rerank。
descriptionbodystring否—Provider 连接描述。
isDefaultbodyboolean否—设为同类型默认 Provider。
isActivebodyboolean否—创建后是否立即参与路由。
timeoutMsbodyinteger否—上游请求超时(毫秒)。
maxRetriesbodyinteger否—最大重试次数。
prioritybodyinteger否—failover 优先级,越小越优先;主 Provider 失败时按升序尝试。
maxInputTokensbodyinteger否—最大输入 token;null 不限。
allowByokbodyboolean否—允许调用方经 X-Provider-Key 头自带上游密钥。

输出:返回 201 + llmGatewayProvider:

字段类型说明
$idstringProvider ID。
$createdAtstring创建时间(ISO 8601)。
$updatedAtstring最近更新时间(ISO 8601)。
connectionNamestring连接名,项目内唯一。
providerTypestring上游类型:openai / anthropic / dashscope / theta。
baseUrlstring上游 API base URL。
apiKeySetboolean是否已配置上游密钥;响应永不回显 apiKey 本体。
defaultModelstring该连接的默认模型。
allowedCapabilitiesstring[]放行能力:chat / embedding / rerank / vlm(由各模型清单派生)。
supportedModelsstring[]兼容字段:全部支持模型 ID 的汇总(服务端派生)。
chatModelsstring[]可用于 chat completions 的模型 ID。
embeddingModelsstring[]可用于 embeddings 的模型 ID。
rerankModelsstring[]可用于 rerank 的模型 ID。
vlmModelsstring[]可用于视觉理解的模型 ID(复用 chat completions 端点)。
descriptionstring连接描述。
statusstring运行状态:active / paused。
isDefaultboolean是否为同类型默认 Provider。
priorityintegerfailover 优先级,数值越小越优先。
timeoutMsinteger上游请求超时(毫秒)。
maxRetriesinteger最大重试次数。
maxInputTokensinteger最大输入 token;null 表示不限。
allowByokboolean是否允许调用方经 X-Provider-Key 头自带上游密钥(BYOK)。
healthStatusstring健康状态:HEALTHY / UNHEALTHY / UNKNOWN。
healthMessagestring最近一次模型校验失败的摘要。
lastValidatedAtstring最近一次健康校验时间。
lastUsedAtstring最近一次被路由使用的时间。
memoryEmbeddingReferencedboolean是否已被项目 Memory embedding 配置引用;null 表示本次响应未评估约束。
immutableFieldsstring[]被 Memory 引用期间不可修改的字段列表。
deleteAllowedboolean当前是否允许删除;null 表示未评估。
credentialPolicystring凭据变更策略:mutable / rotate-only;空表示未评估。

调用示例:

curl -X POST "https://<your-endpoint>/v1/llm-gateway/providers" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "providerId": "openai-prod",
    "connectionName": "openai-production",
    "providerType": "openai",
    "baseUrl": "https://api.openai.com",
    "apiKey": "sk-xxxxxxxxxxxxxxxx",
    "defaultModel": "gpt-4o-mini",
    "chatModels": ["gpt-4o-mini"],
    "embeddingModels": ["text-embedding-3-small"],
    "priority": 0,
    "timeoutMs": 60000,
    "maxRetries": 3,
    "isActive": true,
    "description": "生产 OpenAI 连接"
  }'

响应示例:

{
  "$id": "openai-prod",
  "$createdAt": "2026-08-01T03:12:45.231+00:00",
  "$updatedAt": "2026-08-01T03:12:45.231+00:00",
  "connectionName": "openai-production",
  "providerType": "openai",
  "baseUrl": "https://api.openai.com",
  "apiKeySet": true,
  "defaultModel": "gpt-4o-mini",
  "allowedCapabilities": [
    "chat",
    "embedding"
  ],
  "supportedModels": [
    "gpt-4o-mini",
    "text-embedding-3-small"
  ],
  "chatModels": [
    "gpt-4o-mini"
  ],
  "embeddingModels": [
    "text-embedding-3-small"
  ],
  "rerankModels": [],
  "vlmModels": [],
  "description": "生产 OpenAI 连接",
  "status": "active",
  "isDefault": true,
  "priority": 0,
  "timeoutMs": 60000,
  "maxRetries": 3,
  "maxInputTokens": 128000,
  "allowByok": false,
  "healthStatus": "HEALTHY",
  "healthMessage": "",
  "lastValidatedAt": "2026-08-01T03:13:02.884+00:00",
  "lastUsedAt": "2026-09-01T08:00:11.102+00:00",
  "memoryEmbeddingReferenced": false,
  "immutableFields": [],
  "deleteAllowed": true,
  "credentialPolicy": "mutable"
}

GET /v1/llm-gateway/providers/{providerId}

按 ID 读取单个 Provider:返回路由配置与健康元数据,永不暴露上游密钥原文。

输入:

参数位置类型必填默认/枚举说明
providerIdpathstring是—Provider ID。

输出:返回 llmGatewayProvider:

字段类型说明
$idstringProvider ID。
$createdAtstring创建时间(ISO 8601)。
$updatedAtstring最近更新时间(ISO 8601)。
connectionNamestring连接名,项目内唯一。
providerTypestring上游类型:openai / anthropic / dashscope / theta。
baseUrlstring上游 API base URL。
apiKeySetboolean是否已配置上游密钥;响应永不回显 apiKey 本体。
defaultModelstring该连接的默认模型。
allowedCapabilitiesstring[]放行能力:chat / embedding / rerank / vlm(由各模型清单派生)。
supportedModelsstring[]兼容字段:全部支持模型 ID 的汇总(服务端派生)。
chatModelsstring[]可用于 chat completions 的模型 ID。
embeddingModelsstring[]可用于 embeddings 的模型 ID。
rerankModelsstring[]可用于 rerank 的模型 ID。
vlmModelsstring[]可用于视觉理解的模型 ID(复用 chat completions 端点)。
descriptionstring连接描述。
statusstring运行状态:active / paused。
isDefaultboolean是否为同类型默认 Provider。
priorityintegerfailover 优先级,数值越小越优先。
timeoutMsinteger上游请求超时(毫秒)。
maxRetriesinteger最大重试次数。
maxInputTokensinteger最大输入 token;null 表示不限。
allowByokboolean是否允许调用方经 X-Provider-Key 头自带上游密钥(BYOK)。
healthStatusstring健康状态:HEALTHY / UNHEALTHY / UNKNOWN。
healthMessagestring最近一次模型校验失败的摘要。
lastValidatedAtstring最近一次健康校验时间。
lastUsedAtstring最近一次被路由使用的时间。
memoryEmbeddingReferencedboolean是否已被项目 Memory embedding 配置引用;null 表示本次响应未评估约束。
immutableFieldsstring[]被 Memory 引用期间不可修改的字段列表。
deleteAllowedboolean当前是否允许删除;null 表示未评估。
credentialPolicystring凭据变更策略:mutable / rotate-only;空表示未评估。

调用示例:

curl "https://<your-endpoint>/v1/llm-gateway/providers/openai-prod" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "$id": "openai-prod",
  "$createdAt": "2026-08-01T03:12:45.231+00:00",
  "$updatedAt": "2026-08-01T03:12:45.231+00:00",
  "connectionName": "openai-production",
  "providerType": "openai",
  "baseUrl": "https://api.openai.com",
  "apiKeySet": true,
  "defaultModel": "gpt-4o-mini",
  "allowedCapabilities": [
    "chat",
    "embedding"
  ],
  "supportedModels": [
    "gpt-4o-mini",
    "text-embedding-3-small"
  ],
  "chatModels": [
    "gpt-4o-mini"
  ],
  "embeddingModels": [
    "text-embedding-3-small"
  ],
  "rerankModels": [],
  "vlmModels": [],
  "description": "生产 OpenAI 连接",
  "status": "active",
  "isDefault": true,
  "priority": 0,
  "timeoutMs": 60000,
  "maxRetries": 3,
  "maxInputTokens": 128000,
  "allowByok": false,
  "healthStatus": "HEALTHY",
  "healthMessage": "",
  "lastValidatedAt": "2026-08-01T03:13:02.884+00:00",
  "lastUsedAt": "2026-09-01T08:00:11.102+00:00",
  "memoryEmbeddingReferenced": false,
  "immutableFields": [],
  "deleteAllowed": true,
  "credentialPolicy": "mutable"
}

PATCH /v1/llm-gateway/providers/{providerId}

更新 Provider:仅修改显式传入的字段;能力模型清单可单独更新,服务端重新派生 allowedCapabilities 与 supportedModels。

输入:

参数位置类型必填默认/枚举说明
providerIdpathstring是—Provider ID。
connectionNamebodystring否—连接名(唯一性校验同创建)。
providerTypebodystring否枚举 openai, anthropic, dashscope, theta上游类型;仅改类型时保留显式自定义路径,若 rerankPath 为旧类型内置默认值则迁移为新类型默认。
baseUrlbodystring否—上游 base URL。
apiKeybodystring否—传空字符串清除已存密钥;省略字段保持现有密钥不变。
defaultModelbodystring否—默认模型。
allowedCapabilitiesbodystring[]否—兼容字段,一般不直接传。
supportedModelsbodystring[]否—仅传旧字段时沿用旧版兼容语义。
chatModelsbodystring[]否—单独更新 chat 清单时,其他三个能力清单保持不变。
embeddingModelsbodystring[]否—单独更新 embedding 清单。
rerankModelsbodystring[]否—单独更新 rerank 清单。
vlmModelsbodystring[]否—单独更新 VLM 清单。
chatCompletionsPathbodystring否—chat completions 路径覆盖。
embeddingsPathbodystring否—embeddings 路径覆盖。
rerankPathbodystring否—rerank 路径覆盖。
descriptionbodystring否—连接描述。
isDefaultbodyboolean否—设为同类型默认。
isActivebodyboolean否—false 使 Provider 退出路由。
timeoutMsbodyinteger否—上游超时(毫秒)。
maxRetriesbodyinteger否—最大重试次数。
prioritybodyinteger否—failover 优先级。
maxInputTokensbodyinteger否—最大输入 token。
allowByokbodyboolean否—是否允许 BYOK。

输出:返回更新后的 llmGatewayProvider:

字段类型说明
$idstringProvider ID。
$createdAtstring创建时间(ISO 8601)。
$updatedAtstring最近更新时间(ISO 8601)。
connectionNamestring连接名,项目内唯一。
providerTypestring上游类型:openai / anthropic / dashscope / theta。
baseUrlstring上游 API base URL。
apiKeySetboolean是否已配置上游密钥;响应永不回显 apiKey 本体。
defaultModelstring该连接的默认模型。
allowedCapabilitiesstring[]放行能力:chat / embedding / rerank / vlm(由各模型清单派生)。
supportedModelsstring[]兼容字段:全部支持模型 ID 的汇总(服务端派生)。
chatModelsstring[]可用于 chat completions 的模型 ID。
embeddingModelsstring[]可用于 embeddings 的模型 ID。
rerankModelsstring[]可用于 rerank 的模型 ID。
vlmModelsstring[]可用于视觉理解的模型 ID(复用 chat completions 端点)。
descriptionstring连接描述。
statusstring运行状态:active / paused。
isDefaultboolean是否为同类型默认 Provider。
priorityintegerfailover 优先级,数值越小越优先。
timeoutMsinteger上游请求超时(毫秒)。
maxRetriesinteger最大重试次数。
maxInputTokensinteger最大输入 token;null 表示不限。
allowByokboolean是否允许调用方经 X-Provider-Key 头自带上游密钥(BYOK)。
healthStatusstring健康状态:HEALTHY / UNHEALTHY / UNKNOWN。
healthMessagestring最近一次模型校验失败的摘要。
lastValidatedAtstring最近一次健康校验时间。
lastUsedAtstring最近一次被路由使用的时间。
memoryEmbeddingReferencedboolean是否已被项目 Memory embedding 配置引用;null 表示本次响应未评估约束。
immutableFieldsstring[]被 Memory 引用期间不可修改的字段列表。
deleteAllowedboolean当前是否允许删除;null 表示未评估。
credentialPolicystring凭据变更策略:mutable / rotate-only;空表示未评估。

调用示例:

curl -X PATCH "https://<your-endpoint>/v1/llm-gateway/providers/openai-prod" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "priority": 10,
    "timeoutMs": 30000,
    "maxRetries": 2
  }'

响应示例:

{
  "$id": "openai-prod",
  "$createdAt": "2026-08-01T03:12:45.231+00:00",
  "$updatedAt": "2026-08-01T03:12:45.231+00:00",
  "connectionName": "openai-production",
  "providerType": "openai",
  "baseUrl": "https://api.openai.com",
  "apiKeySet": true,
  "defaultModel": "gpt-4o-mini",
  "allowedCapabilities": [
    "chat",
    "embedding"
  ],
  "supportedModels": [
    "gpt-4o-mini",
    "text-embedding-3-small"
  ],
  "chatModels": [
    "gpt-4o-mini"
  ],
  "embeddingModels": [
    "text-embedding-3-small"
  ],
  "rerankModels": [],
  "vlmModels": [],
  "description": "生产 OpenAI 连接",
  "status": "active",
  "isDefault": true,
  "priority": 0,
  "timeoutMs": 60000,
  "maxRetries": 3,
  "maxInputTokens": 128000,
  "allowByok": false,
  "healthStatus": "HEALTHY",
  "healthMessage": "",
  "lastValidatedAt": "2026-08-01T03:13:02.884+00:00",
  "lastUsedAt": "2026-09-01T08:00:11.102+00:00",
  "memoryEmbeddingReferenced": false,
  "immutableFields": [],
  "deleteAllowed": true,
  "credentialPolicy": "mutable"
}

DELETE /v1/llm-gateway/providers/{providerId}

删除 Provider 连接:从路由中移除,之后不再承接该项目的模型请求。

输入:

参数位置类型必填默认/枚举说明
providerIdpathstring是—Provider ID。

输出:204 No Content,无响应体。

调用示例:

curl -X DELETE "https://<your-endpoint>/v1/llm-gateway/providers/openai-prod" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:204 No Content:无响应体(删除成功)。

GET /v1/llm-gateway/providers/{providerId}/health

对 Provider 全部 (能力, 模型) 组合执行实时校验并更新健康状态;兼容接口,仍返回最新 Provider 对象。

输入:

参数位置类型必填默认/枚举说明
providerIdpathstring是—Provider ID。

输出:返回携带最新健康状态的 llmGatewayProvider(关注 healthStatus / healthMessage / lastValidatedAt):

字段类型说明
$idstringProvider ID。
$createdAtstring创建时间(ISO 8601)。
$updatedAtstring最近更新时间(ISO 8601)。
connectionNamestring连接名,项目内唯一。
providerTypestring上游类型:openai / anthropic / dashscope / theta。
baseUrlstring上游 API base URL。
apiKeySetboolean是否已配置上游密钥;响应永不回显 apiKey 本体。
defaultModelstring该连接的默认模型。
allowedCapabilitiesstring[]放行能力:chat / embedding / rerank / vlm(由各模型清单派生)。
supportedModelsstring[]兼容字段:全部支持模型 ID 的汇总(服务端派生)。
chatModelsstring[]可用于 chat completions 的模型 ID。
embeddingModelsstring[]可用于 embeddings 的模型 ID。
rerankModelsstring[]可用于 rerank 的模型 ID。
vlmModelsstring[]可用于视觉理解的模型 ID(复用 chat completions 端点)。
descriptionstring连接描述。
statusstring运行状态:active / paused。
isDefaultboolean是否为同类型默认 Provider。
priorityintegerfailover 优先级,数值越小越优先。
timeoutMsinteger上游请求超时(毫秒)。
maxRetriesinteger最大重试次数。
maxInputTokensinteger最大输入 token;null 表示不限。
allowByokboolean是否允许调用方经 X-Provider-Key 头自带上游密钥(BYOK)。
healthStatusstring健康状态:HEALTHY / UNHEALTHY / UNKNOWN。
healthMessagestring最近一次模型校验失败的摘要。
lastValidatedAtstring最近一次健康校验时间。
lastUsedAtstring最近一次被路由使用的时间。
memoryEmbeddingReferencedboolean是否已被项目 Memory embedding 配置引用;null 表示本次响应未评估约束。
immutableFieldsstring[]被 Memory 引用期间不可修改的字段列表。
deleteAllowedboolean当前是否允许删除;null 表示未评估。
credentialPolicystring凭据变更策略:mutable / rotate-only;空表示未评估。

调用示例:

curl "https://<your-endpoint>/v1/llm-gateway/providers/openai-prod/health" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "$id": "openai-prod",
  "$createdAt": "2026-08-01T03:12:45.231+00:00",
  "$updatedAt": "2026-08-01T03:12:45.231+00:00",
  "connectionName": "openai-production",
  "providerType": "openai",
  "baseUrl": "https://api.openai.com",
  "apiKeySet": true,
  "defaultModel": "gpt-4o-mini",
  "allowedCapabilities": [
    "chat",
    "embedding"
  ],
  "supportedModels": [
    "gpt-4o-mini",
    "text-embedding-3-small"
  ],
  "chatModels": [
    "gpt-4o-mini"
  ],
  "embeddingModels": [
    "text-embedding-3-small"
  ],
  "rerankModels": [],
  "vlmModels": [],
  "description": "生产 OpenAI 连接",
  "status": "active",
  "isDefault": true,
  "priority": 0,
  "timeoutMs": 60000,
  "maxRetries": 3,
  "maxInputTokens": 128000,
  "allowByok": false,
  "healthStatus": "UNHEALTHY",
  "healthMessage": "Model validation failed: 1 invalid, 0 unavailable, 0 skipped.",
  "lastValidatedAt": "2026-09-14T02:00:11.400+00:00",
  "lastUsedAt": "2026-09-01T08:00:11.102+00:00",
  "memoryEmbeddingReferenced": false,
  "immutableFields": [],
  "deleteAllowed": true,
  "credentialPolicy": "mutable"
}

POST /v1/llm-gateway/providers/{providerId}/health-checks

对 Provider 已配置的全部模型做统一合法性校验,返回 Provider、汇总统计与逐模型结果;以 sparse update 方式回写健康字段。

输入:

参数位置类型必填默认/枚举说明
providerIdpathstring是—Provider ID。

输出:返回 llmGatewayProviderHealthCheck:

字段类型说明
providerobject携带最新持久化健康状态的 Provider 对象(字段同 llmGatewayProvider,见 Provider 管理小节,此处不重复列出)。
summaryobject校验汇总(字段见下)。
summary.totalinteger校验结果总数。
summary.validinteger校验通过数量。
summary.invalidinteger校验失败(配置非法)数量。
summary.unavailableinteger上游暂不可用数量。
summary.skippedinteger跳过数量。
summary.durationMsinteger整批校验总耗时(毫秒)。
resultsllmGatewayProviderValidationResult[]逐 (capability, model) 校验结果(字段见下)。
results[].capabilitystring该校验针对的能力。
results[].modelstring被校验的模型 ID。
results[].statusstring结果:valid / invalid / unavailable / skipped。
results[].codestring稳定机器可读结果码(如 ok)。
results[].retryableboolean不做配置变更、稍后重试是否可能成功。
results[].latencyMsinteger单次探测耗时(毫秒)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/llm-gateway/providers/openai-prod/health-checks" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "provider": {
    "$id": "openai-prod",
    "$createdAt": "2026-08-01T03:12:45.231+00:00",
    "$updatedAt": "2026-08-01T03:12:45.231+00:00",
    "connectionName": "openai-production",
    "providerType": "openai",
    "baseUrl": "https://api.openai.com",
    "apiKeySet": true,
    "defaultModel": "gpt-4o-mini",
    "allowedCapabilities": [
      "chat",
      "embedding"
    ],
    "supportedModels": [
      "gpt-4o-mini",
      "text-embedding-3-small"
    ],
    "chatModels": [
      "gpt-4o-mini"
    ],
    "embeddingModels": [
      "text-embedding-3-small"
    ],
    "rerankModels": [],
    "vlmModels": [],
    "description": "生产 OpenAI 连接",
    "status": "active",
    "isDefault": true,
    "priority": 0,
    "timeoutMs": 60000,
    "maxRetries": 3,
    "maxInputTokens": 128000,
    "allowByok": false,
    "healthStatus": "HEALTHY",
    "healthMessage": "",
    "lastValidatedAt": "2026-08-01T03:13:02.884+00:00",
    "lastUsedAt": "2026-09-01T08:00:11.102+00:00",
    "memoryEmbeddingReferenced": false,
    "immutableFields": [],
    "deleteAllowed": true,
    "credentialPolicy": "mutable"
  },
  "summary": {
    "total": 2,
    "valid": 1,
    "invalid": 1,
    "unavailable": 0,
    "skipped": 0,
    "durationMs": 256
  },
  "results": [
    {
      "capability": "chat",
      "model": "gpt-4o-mini",
      "status": "valid",
      "code": "ok",
      "retryable": false,
      "latencyMs": 128
    },
    {
      "capability": "embedding",
      "model": "text-embedding-3-small",
      "status": "invalid",
      "code": "model_not_allowed",
      "retryable": false,
      "latencyMs": 94
    }
  ]
}

GET /v1/llm-gateway/providers/{providerId}/models

直接从上游拉取实际可用模型清单(模型发现):当前面向 dashscope Provider;其他兼容类型需手工维护模型清单。

输入:

参数位置类型必填默认/枚举说明
providerIdpathstring是—Provider ID。

输出:返回纯 ID 形态 { "models": string[], "total": number }(不是 llmGatewayModel 对象数组)。

调用示例:

curl "https://<your-endpoint>/v1/llm-gateway/providers/openai-prod/models" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "models": [
    "qwen-plus",
    "qwen-max",
    "text-embedding-v3"
  ],
  "total": 3
}

POST /v1/llm-gateway/providers/cache/refresh

强制重载当前项目在内存中的 Provider 路由缓存:批量变更 Provider 后让新路由快照在当前 Worker 立即生效。

输入:无 path/query/body 参数。

输出:204 No Content,无响应体。

调用示例:

curl -X POST "https://<your-endpoint>/v1/llm-gateway/providers/cache/refresh" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:204 No Content:无响应体(缓存已刷新)。

POST /v1/llm-gateway/provider-model-discoveries

用百炼 DashScope 凭证拉取账号可用模型,并按内置模型目录预分类为 Chat / Embedding / Rerank / VLM,供创建或编辑 Provider 时取用。

输入:

参数位置类型必填默认/枚举说明
providerIdbodystring否—已有 Provider ID;编辑语境使用,复用已保存凭证。
providerTypebodystring否枚举 openai, anthropic, dashscope, theta创建语境使用(无 providerId 时必填),枚举同 Provider。
baseUrlbodystring否—非空时覆盖已存 Provider 的 base URL。
apiKeybodystring否—非空时覆盖已存 Provider 的密钥。

输出:返回发现结果:按 chat / embedding / rerank / vlm 预分类的模型清单与未分类预览。

调用示例:

curl -X POST "https://<your-endpoint>/v1/llm-gateway/provider-model-discoveries" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "providerType": "dashscope",
    "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode",
    "apiKey": "sk-xxxxxxxxxxxxxxxx"
  }'

响应示例:响应为发现结果 JSON(按能力预分类的模型清单 + 未分类预览,字段以实际响应为准):仅作预览,不自动写入任何 Provider。

网关子密钥

GET /v1/llm-gateway/keys

列出当前项目的网关子密钥:永不返回明文,用 keyPrefix、名称、启停、过期时间与最近使用时间识别密钥。

输入:无 path/query/body 参数。

输出:返回 llmGatewayKeyList(total + keys[]),元素为 llmGatewayKey(其中 key 明文恒为空/不回显):

字段类型说明
$idstringKey ID。
$createdAtstring创建时间(ISO 8601)。
$updatedAtstring最近更新时间(ISO 8601)。
keystring完整明文密钥(abk_ 前缀),仅在创建响应中出现一次,之后任何读取端点都不再返回。
keyPrefixstring密钥展示前缀(非敏感),用于在列表中识别密钥。
namestring密钥名称。
descriptionstring密钥描述。
allowedModelsstring[]允许调用的模型 ID 白名单;["*"] 表示放行全部模型。
monthlyTokenBudgetinteger月度 token 预算;null 表示不限。按三级用量 UTC 日归集数据滚动累计,耗尽后该密钥的请求被拒。
monthlyTokensUsedinteger当前计费周期已消耗 token 数。
budgetResetAtstring下一个月度预算重置时间。
rateLimitinteger每分钟请求上限;null 使用项目级默认限流。
isActiveboolean是否启用;false 时该密钥立即不可用。
expiresAtstring过期时间(ISO 8601);null 表示永不过期。
lastUsedAtstring最近一次使用时间。

调用示例:

curl "https://<your-endpoint>/v1/llm-gateway/keys" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "total": 1,
  "keys": [
    {
      "$id": "key_mobile_chat",
      "$createdAt": "2026-08-12T09:20:00.000+00:00",
      "$updatedAt": "2026-08-12T09:20:00.000+00:00",
      "key": "",
      "keyPrefix": "abk_proj6789_aB3xK9",
      "name": "mobile-app-chat",
      "description": "移动端聊天功能专用",
      "allowedModels": [
        "gpt-4o-mini"
      ],
      "monthlyTokenBudget": 1000000,
      "monthlyTokensUsed": 45230,
      "budgetResetAt": "2026-09-01T00:00:00.000+00:00",
      "rateLimit": 60,
      "isActive": true,
      "expiresAt": null,
      "lastUsedAt": "2026-09-10T14:02:33.000+00:00"
    }
  ]
}

POST /v1/llm-gateway/keys

签发网关子密钥:面向下游应用的受限凭据,只能调用数据面端点,受 allowedModels / 预算 / 限流 / 有效期约束。

输入:

参数位置类型必填默认/枚举说明
keyIdbodystring是—子密钥 ID,自定义或 ID.unique()。
namebodystring是—密钥名称。
descriptionbodystring否—密钥描述。
allowedModelsbodystring[]否—模型白名单;["*"] 放行全部。请求模型不在白名单时数据面返回 403。
monthlyTokenBudgetbodyinteger否—月度 token 预算;null 不限。耗尽后该密钥请求被拒,直到下次重置。
rateLimitbodyinteger否—每分钟请求上限;null 使用全局默认。
expiresAtbodystring否—过期时间(ISO 8601);null 永不过期。

输出:返回 201 + llmGatewayKey,仅此次响应包含明文 key(abk_ 前缀),之后只能看到 keyPrefix:

字段类型说明
$idstringKey ID。
$createdAtstring创建时间(ISO 8601)。
$updatedAtstring最近更新时间(ISO 8601)。
keystring完整明文密钥(abk_ 前缀),仅在创建响应中出现一次,之后任何读取端点都不再返回。
keyPrefixstring密钥展示前缀(非敏感),用于在列表中识别密钥。
namestring密钥名称。
descriptionstring密钥描述。
allowedModelsstring[]允许调用的模型 ID 白名单;["*"] 表示放行全部模型。
monthlyTokenBudgetinteger月度 token 预算;null 表示不限。按三级用量 UTC 日归集数据滚动累计,耗尽后该密钥的请求被拒。
monthlyTokensUsedinteger当前计费周期已消耗 token 数。
budgetResetAtstring下一个月度预算重置时间。
rateLimitinteger每分钟请求上限;null 使用项目级默认限流。
isActiveboolean是否启用;false 时该密钥立即不可用。
expiresAtstring过期时间(ISO 8601);null 表示永不过期。
lastUsedAtstring最近一次使用时间。

调用示例:

curl -X POST "https://<your-endpoint>/v1/llm-gateway/keys" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "keyId": "key_mobile_chat",
    "name": "mobile-app-chat",
    "description": "移动端聊天功能专用",
    "allowedModels": ["gpt-4o-mini"],
    "monthlyTokenBudget": 1000000,
    "rateLimit": 60,
    "expiresAt": null
  }'

响应示例:

{
  "$id": "key_mobile_chat",
  "$createdAt": "2026-08-12T09:20:00.000+00:00",
  "$updatedAt": "2026-08-12T09:20:00.000+00:00",
  "key": "abk_proj6789_aB3xK9mN2pQ7wR4tY8vF1jH5cE0iU6oL3sA9bD2gX7zW4nM",
  "keyPrefix": "abk_proj6789_aB3xK9",
  "name": "mobile-app-chat",
  "description": "移动端聊天功能专用",
  "allowedModels": [
    "gpt-4o-mini"
  ],
  "monthlyTokenBudget": 1000000,
  "monthlyTokensUsed": 45230,
  "budgetResetAt": "2026-09-01T00:00:00.000+00:00",
  "rateLimit": 60,
  "isActive": true,
  "expiresAt": null,
  "lastUsedAt": "2026-09-10T14:02:33.000+00:00"
}

PATCH /v1/llm-gateway/keys/{keyId}

更新子密钥:改名、调整模型白名单、限流、预算、启停或过期时间;仅修改显式传入的字段。

输入:

参数位置类型必填默认/枚举说明
keyIdpathstring是—子密钥 ID。
namebodystring否—密钥名称。
descriptionbodystring否—密钥描述。
allowedModelsbodystring[]否—模型白名单。
monthlyTokenBudgetbodyinteger否—月度 token 预算。
rateLimitbodyinteger否—每分钟请求上限。
isActivebodyboolean否—false 立即禁用。
expiresAtbodystring否—过期时间(ISO 8601)。

输出:返回更新后的 llmGatewayKey:

字段类型说明
$idstringKey ID。
$createdAtstring创建时间(ISO 8601)。
$updatedAtstring最近更新时间(ISO 8601)。
keystring完整明文密钥(abk_ 前缀),仅在创建响应中出现一次,之后任何读取端点都不再返回。
keyPrefixstring密钥展示前缀(非敏感),用于在列表中识别密钥。
namestring密钥名称。
descriptionstring密钥描述。
allowedModelsstring[]允许调用的模型 ID 白名单;["*"] 表示放行全部模型。
monthlyTokenBudgetinteger月度 token 预算;null 表示不限。按三级用量 UTC 日归集数据滚动累计,耗尽后该密钥的请求被拒。
monthlyTokensUsedinteger当前计费周期已消耗 token 数。
budgetResetAtstring下一个月度预算重置时间。
rateLimitinteger每分钟请求上限;null 使用项目级默认限流。
isActiveboolean是否启用;false 时该密钥立即不可用。
expiresAtstring过期时间(ISO 8601);null 表示永不过期。
lastUsedAtstring最近一次使用时间。

调用示例:

curl -X PATCH "https://<your-endpoint>/v1/llm-gateway/keys/key_mobile_chat" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "rateLimit": 30,
    "isActive": false
  }'

响应示例:

{
  "$id": "key_mobile_chat",
  "$createdAt": "2026-08-12T09:20:00.000+00:00",
  "$updatedAt": "2026-09-14T02:10:00.000+00:00",
  "key": "abk_proj6789_aB3xK9mN2pQ7wR4tY8vF1jH5cE0iU6oL3sA9bD2gX7zW4nM",
  "keyPrefix": "abk_proj6789_aB3xK9",
  "name": "mobile-app-chat",
  "description": "移动端聊天功能专用",
  "allowedModels": [
    "gpt-4o-mini"
  ],
  "monthlyTokenBudget": 1000000,
  "monthlyTokensUsed": 45230,
  "budgetResetAt": "2026-09-01T00:00:00.000+00:00",
  "rateLimit": 30,
  "isActive": false,
  "expiresAt": null,
  "lastUsedAt": "2026-09-10T14:02:33.000+00:00"
}

DELETE /v1/llm-gateway/keys/{keyId}

永久删除子密钥(硬删除,不经过软吊销):文档立即移除,密钥随即无法调用执行端点。

输入:

参数位置类型必填默认/枚举说明
keyIdpathstring是—子密钥 ID。

输出:204 No Content,无响应体。

调用示例:

curl -X DELETE "https://<your-endpoint>/v1/llm-gateway/keys/key_mobile_chat" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:204 No Content:无响应体(密钥已吊销)。

试用 Provider 绑定

GET /v1/llm-gateway/trial-providers

列出平台提供的可绑定试用 Provider 清单:绑定前先在此确认平台 provider ID 与试用额度。

输入:无 path/query/body 参数。

输出:返回试用 provider 清单(泛化 schema any:元素含平台 provider ID、能力与试用额度信息,字段以实际响应为准)。

调用示例:

curl "https://<your-endpoint>/v1/llm-gateway/trial-providers" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:响应为试用 provider 数组文档(泛化 schema,字段以实际响应为准);把其中的平台 provider ID 用于创建绑定。

GET /v1/llm-gateway/trial-provider-bindings

列出当前项目生效的平台试用 Provider 绑定。

输入:无 path/query/body 参数。

输出:返回绑定列表(泛化 schema any:每条含 bindingId、平台 provider 与项目关联、额度状态等信息,字段以实际响应为准)。

调用示例:

curl "https://<your-endpoint>/v1/llm-gateway/trial-provider-bindings" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:响应为绑定数组文档(泛化 schema,字段以实际响应为准)。

POST /v1/llm-gateway/trial-provider-bindings

把一个平台试用 Provider 绑定到账号名下项目:绑定成功(201)后以 trial:<bindingId> 参与模型路由。

输入:

参数位置类型必填默认/枚举说明
providerIdbodystring是—平台 provider ID(来自 GET /llm-gateway/trial-providers)。

输出:返回 201 + 绑定对象(泛化 schema any,字段以实际响应为准)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/llm-gateway/trial-provider-bindings" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "providerId": "trial-dashscope-gte-rerank" }'

响应示例:201:响应为绑定对象 JSON(泛化 schema,字段以实际响应为准),记下 bindingId 供后续端点使用。

GET /v1/llm-gateway/trial-provider-bindings/{bindingId}

读取单个试用 Provider 绑定的详情与额度状态。

输入:

参数位置类型必填默认/枚举说明
bindingIdpathstring是—试用绑定 ID。

输出:返回绑定对象(泛化 schema any,字段以实际响应为准)。

调用示例:

curl "https://<your-endpoint>/v1/llm-gateway/trial-provider-bindings/<BINDING_ID>" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:响应为绑定对象 JSON(泛化 schema,字段以实际响应为准)。

DELETE /v1/llm-gateway/trial-provider-bindings/{bindingId}

解除试用 Provider 绑定:trial:<bindingId> 路由随即失效。

输入:

参数位置类型必填默认/枚举说明
bindingIdpathstring是—试用绑定 ID。

输出:204 No Content,无响应体。

调用示例:

curl -X DELETE "https://<your-endpoint>/v1/llm-gateway/trial-provider-bindings/<BINDING_ID>" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:204 No Content:无响应体(已解绑)。

POST /v1/llm-gateway/trial-provider-bindings/{bindingId}/health-checks

对绑定的平台试用 Provider 实测可用性:验证凭证、网络与模型通路。

输入:

参数位置类型必填默认/枚举说明
bindingIdpathstring是—试用绑定 ID。

输出:返回实测结果(泛化 schema any:含健康状态与逐模型校验信息,字段以实际响应为准)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/llm-gateway/trial-provider-bindings/<BINDING_ID>/health-checks" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:响应为健康检查结果 JSON(泛化 schema,字段以实际响应为准)。

错误与边界

与 Server SDK 的对应

service.method端点
LLMGateway.createChatCompletionPOST /llm-gateway/chat/completions
LLMGateway.createMessagePOST /llm-gateway/messages
LLMGateway.createEmbeddingsPOST /llm-gateway/embeddings
LLMGateway.createRerankPOST /llm-gateway/rerank
LLMGateway.listModels / getModel/llm-gateway/models*
LLMGateway.listProviders / createProvider / getProvider / updateProvider / deleteProvider/llm-gateway/providers*
LLMGateway.getProviderHealth / createProviderHealthCheck / listProviderModels / refreshProviderCache.../health*、.../models、.../cache/refresh
LLMGateway.createProviderModelDiscoveryPOST /llm-gateway/provider-model-discoveries
LLMGateway.listKeys / createKey / updateKey / deleteKey/llm-gateway/keys*
LLMGateway.listTrialProviders / listTrialProviderBindings / createTrialProviderBinding / getTrialProviderBinding / deleteTrialProviderBinding / createTrialProviderBindingHealthCheck/llm-gateway/trial-provider*

事实源