Keural API

以 OpenAI Chat Completions 格式调用 Keural 中已登记的模型。

Base URL 的格式为 https://<各环境的公开 API 域名>/llm/v1。公开 API 域名因环境而异，请向管理员确认。

不支持嵌入、图像生成、语音和 Responses API 路径，发送到这些路径将返回 404。

使用流程复制锚点链接

准备事项复制锚点链接

签发 API 密钥复制锚点链接

1. 在账户菜单中打开 设置 → API。在桌面应用和移动应用中，它位于 工具 区域。
2. 在 API keys 标签页中，选择密钥的归属（个人工作区或组织工作区）以及 Model ID。
3. 如有需要，设定 New key expiration (optional, Korea time)。留空则在撤销前一直有效。
4. 点击 Issue key，然后用 Copy key 复制密钥并妥善保管。完整密钥仅在此时显示一次。

• 密钥与所选工作区及一个模型相关联。用量归属于签发密钥的人。
• 同一工作区、同一模型只能有一个密钥。需要新密钥时，请重新签发或撤销现有密钥。
• 丢失密钥后将无法再次查看，请重新签发。重新签发后，之前的密钥立即失效。
• 若没有可签发的模型，请向管理员确认模型的公开设置、套餐和组织 API 权限。

组织成员的 API 权限复制锚点链接

仅适用于组织所有者和管理员。要让成员在组织工作区中获取密钥，管理员需先行允许。所有成员的默认值为阻止。

组织管理 → Organization API 由以下三个区域组成。若没有该菜单，说明 API 功能已关闭，或该账户没有组织管理权限。

成员退出或被移出组织时，该成员在组织中获得的密钥会自动撤销。

连接到客户端复制锚点链接

在兼容 OpenAI API 的应用（聊天客户端、IDE 扩展、自动化工具等）中输入以下三项。

1. 在应用设置中添加 OpenAI 兼容连接（Connection）。
2. 输入 Base URL 和 API Key，然后保存。
3. 从模型列表中选择模型。列表中仅显示与密钥关联的一个模型。
4. 发送一条简短消息，确认是否收到回复。

请求格式如下。

第一个请求复制锚点链接

export KEURAL_API_KEY='your_issued_key'
export KEURAL_BASE_URL='https://<各环境的公开 API 域名>/llm/v1'
export MODEL_ID='签发界面中的模型 ID'

curl "$KEURAL_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $KEURAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"model\":\"$MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"你好。\"}]}"

请求正文中的 model 必须与密钥关联的模型 ID 一致。若前面带有 provider/模型ID 这样的路径，则比较最后一个 / 之后的部分。不一致时返回 403。响应中的 model 始终包含密钥的模型 ID。

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["KEURAL_API_KEY"],
    base_url=os.environ["KEURAL_BASE_URL"],
)
res = client.chat.completions.create(
    model=os.environ["MODEL_ID"],
    messages=[{"role": "user", "content": "你好。"}],
)
print(res.choices[0].message.content)

支持的请求字段复制锚点链接

仅接受以下 18 个顶层字段。发送其他字段将返回 400。值为 null 的可选字段按未发送处理。

消息复制锚点链接

• tool 消息对前面 tool_calls 中的每个 id 只回复一次。
• 图像片段（image_url）只能放在支持图像的模型的 user 消息中。可使用 http 或 https 地址，或 PNG、JPEG、GIF、WebP 的 base64 data URI。detail 为 auto、low 或 high。

正文复制锚点链接

违反正文规则将返回 400，且 param 为 body。

流式传输复制锚点链接

在请求中加入 "stream": true 后，将以 SSE 形式响应。数据块以 data: ... 事件发送，结束时发送 data: [DONE]。加入 "stream_options": {"include_usage": true} 后，在 [DONE] 之前会额外发送一个令牌用量数据块。

加入 include_usage 后，每个数据块都会包含 usage: null，最后一个用量数据块的 choices 为空数组。非流式响应只有在输入和输出令牌都已确认时才会包含 usage。

响应的 id 格式为 chatcmpl-<x-request-id>。所有响应标头都包含 x-request-id。

流式传输过程中出错时，将发送包含错误 JSON 的 data: 事件，然后在没有 [DONE] 的情况下结束连接。单个数据块超过 1MiB，或响应超过 16MiB，则以 503 结束。

curl -N "$KEURAL_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $KEURAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"model\":\"$MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"你好。\"}],\"stream\":true,\"stream_options\":{\"include_usage\":true}}"

使用限制复制锚点链接

按用户、组织和模型分别限制并发请求数、每分钟请求数（RPM）和每分钟令牌数（TPM）。实际数值因环境而异。

每分钟令牌数在接收请求时预先扣除。输入按每 4 个英文字符计 1 个令牌，其他字符按每个字符计 1 个令牌，一张图像计 2,000 个令牌。输出按 max_tokens（最多 4,096）预先扣除，因此只设置所需的输出上限，可获得更多的限额余量。

密钥管理复制锚点链接

在 设置 → API → API keys 标签页中可查看密钥状态（有效、已过期、已撤销），并进行重新签发或撤销。

密钥是以 krl_llm_ 开头的 51 个字符的字符串。每个密钥归属下只能有一个密钥，若已存在，则重新签发。有效期只能设定为今天之后的日期。

查看用量复制锚点链接

API 请求和令牌用量，可在以下两个位置查看。

查询条件复制锚点链接

设定条件后点击 Search。若要反映最近的请求，请点击 Refresh。

界面中显示的值复制锚点链接

• Applied time range (KST)：实际查询的时间范围。开始或结束时间留空，或超过 90 天时，将显示服务器调整后的时间范围。
• Requests 以及 Input tokens · Output tokens · Total tokens 的合计：仅合计已确认的值。未确认的令牌显示为 Unconfirmed。
• 请求列表：每个请求显示请求时间、Model ID、请求状态以及输入、输出、总令牌数。每页显示 20 条，通过 Previous 和 Next 翻页。

点击某行的 Request details 可显示以下值。

流式请求无需 stream_options.include_usage 也会记录用量。请求中途断开时，可能保留为 Partially confirmed 或 Unconfirmed。

错误格式复制锚点链接

错误以 OpenAI 兼容格式返回。

{
  "error": {
    "message": "可供人阅读的错误说明",
    "type": "authentication_error",
    "code": "invalid_api_key",
    "param": null
  }
}

type 由状态码决定，code 用于区分原因。

故障排除复制锚点链接

若问题仍未解决，请附上以下信息联系管理员。请勿发送密钥全文和提示词内容。

• 发生时间
• 使用的模型 ID
• 客户端应用的名称和版本
• 响应标头中的 x-request-id
• 界面上显示的错误信息