UniGateway Kimi K3 模型支持#

本文说明如何通过 UniGateway 调用 Kimi K3 模型。Kimi K3 的模型 ID 为 kimi-k3，使用 UniGateway 的 OpenAI 兼容 Chat Completions API。

Kimi K3 始终启用思考模式，支持文本和图像输入、流式输出、结构化输出、Partial Mode、上下文缓存和工具调用。上述能力均可通过本接口使用。模型能力、价格、可用性和上游状态以 UniGateway 模型库 与接口实时返回为准。

准备工作#

请前往 UniGateway API Keys 创建或获取 API Key。

将 API Key 保存为服务端环境变量：

export UNIGATEWAY_API_KEY="<YOUR_UNIGATEWAY_API_KEY>"
export SESSION_ID="<SESSION_ID>"

Windows PowerShell：

$env:UNIGATEWAY_API_KEY = "<YOUR_UNIGATEWAY_API_KEY>"
$env:SESSION_ID = "<SESSION_ID>"

确认 API Key 可以使用 kimi-k3：

curl https://api.unigateway.ai/v1/models \
  -H "Authorization: Bearer $UNIGATEWAY_API_KEY"

模型列表中必须存在精确 ID kimi-k3。模型可用性受账户权限、模型白名单和上游状态影响。

接口信息#

UniGateway 不保存 Chat Completions 的消息历史。多轮对话和工具调用时，应用必须自行保存历史并在下一次请求中传入。

X-Session-Id#

为优化缓存命中和渠道亲和，建议在 Chat Completions 请求头中传入 X-Session-Id。同一逻辑会话的所有请求复用同一个稳定值；开始新会话时生成新值。

X-Session-Id 应使用 UUID 或应用生成的随机标识，不要包含用户名、手机号、API Key、访问令牌或其他敏感信息。稳定复用该请求头有助于提升渠道亲和性和缓存命中效果。

基础调用#

请求字段#

Kimi K3 的 temperature、top_p、n、presence_penalty 和 frequency_penalty 使用固定值。不要显式传入这些参数。

cURL 示例#

curl https://api.unigateway.ai/v1/chat/completions \
  -H "Authorization: Bearer $UNIGATEWAY_API_KEY" \
  -H "X-Session-Id: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [
      {"role": "user", "content": "用一句话介绍 Kimi K3。"}
    ]
  }'

Python 示例#

pip install --upgrade "openai>=1.0"

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["UNIGATEWAY_API_KEY"],
    base_url="https://api.unigateway.ai/v1",
)

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "用一句话介绍 Kimi K3。"}],
    extra_headers={"X-Session-Id": "<SESSION_ID>"},
)
print(response.choices[0].message.content)

推理与流式输出#

Kimi K3 始终启用思考模式。使用请求顶层 reasoning_effort 选择 low、high 或 max。

response = client.chat.completions.create(
    model="kimi-k3",
    reasoning_effort="high",
    messages=[{"role": "user", "content": "证明根号 2 是无理数。"}],
)
print(response.choices[0].message.content)

流式响应会分别返回推理增量 reasoning_content 和答案增量 content。应用应允许任一字段在单个增量中为空。

stream = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "解释为什么天空是蓝色的。"}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta
    if getattr(delta, "reasoning_content", None):
        print(delta.reasoning_content, end="", flush=True)
    if delta.content:
        print(delta.content, end="", flush=True)

多轮对话时，必须将 API 返回的完整 assistant message 原样加入下一次请求，不要只保留 content。

模型能力#

Kimi K3 的上下文窗口为 1M token；实际并发、RPM、TPM、TPD 和账户可用上限以接口返回为准。max_completion_tokens 默认 131072，最大 1048576。

工具调用#

在每次请求顶层的 tools 中声明工具。收到 tool_calls 后，应用执行对应函数，并按顺序追加完整 assistant message 与对应的 tool 消息，再次调用接口。工具最多 128 个。

tool_choice 的可用值：

• auto：默认值，由模型决定是否调用工具。
• none：禁止本次请求调用工具。
• required：要求本轮至少调用一个工具。
• {"type":"function","function":{"name":"<function-name>"}}：强制调用指定函数。

Kimi K3 支持使用 {"type":"function","function":{"name":"..."}} 强制指定单个函数。函数名称必须与 tools 中的定义完全一致，应用仍需执行函数并回传对应的 tool_call_id。

import json

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "查询指定城市的天气。",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
            "additionalProperties": False,
        },
        "strict": True,
    },
}]
messages = [{"role": "user", "content": "查询北京天气。"}]

response = client.chat.completions.create(
    model="kimi-k3", messages=messages, tools=tools, tool_choice="required"
)
assistant_message = response.choices[0].message
messages.append(assistant_message.model_dump(exclude_none=True))

for tool_call in assistant_message.tool_calls or []:
    arguments = json.loads(tool_call.function.arguments)
    messages.append({
        "role": "tool",
        "tool_call_id": tool_call.id,
        "content": json.dumps({"city": arguments["city"], "condition": "sunny"}),
    })

final_response = client.chat.completions.create(
    model="kimi-k3", messages=messages, tools=tools
)
print(final_response.choices[0].message.content)

工具定义请放在每次请求顶层的 tools 字段中；多轮请求也请在每一轮重复传入完整定义。

结构化输出与 Partial Mode#

使用 response_format.type="json_schema" 和 strict: true 约束最终 message.content。只解析 message.content，不要将 reasoning_content 作为 JSON 结果处理。

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "提取：李雷今年 18 岁。"}],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                },
                "required": ["name", "age"],
                "additionalProperties": False,
            },
        },
    },
)
print(response.choices[0].message.content)

Partial Mode 从已有 assistant 文本前缀继续生成，展示时由应用拼接前缀：

prefix = "结论："
response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "说明保持接口兼容的重要性。"},
        {"role": "assistant", "content": prefix, "partial": True},
    ],
)
print(prefix + (response.choices[0].message.content or ""))

图像与缓存#

图像消息的 content 使用对象数组。图像使用 image_url。

import base64
from pathlib import Path

image_data = base64.b64encode(Path("architecture.png").read_bytes()).decode()
response = client.chat.completions.create(
    model="kimi-k3",
    messages=[{
        "role": "user",
        "content": [
            {"type": "image_url", "image_url": {
                "url": f"data:image/png;base64,{image_data}"
            }},
            {"type": "text", "text": "说明图中的系统组件。"},
        ],
    }],
)
print(response.choices[0].message.content)

上下文缓存自动启用，无需设置 cache ID 或 TTL。同一逻辑会话复用稳定的 X-Session-Id，同时保持长 system 前缀不变；当上一请求的 prompt 超过 256 tokens 时，后续请求可尝试命中缓存。通过 usage.prompt_tokens_details.cached_tokens 检查实际命中情况。

安全与计费注意事项#

• 视觉输入、推理 token 和输出 token 均会影响用量。请在应用侧限制文件大小、分辨率、上下文长度和输出上限。
• 工具结果由应用执行并回传。调用外部服务前应验证工具名称、参数、授权范围和目标地址。
• 不要在提示词、工具结果、任务日志或错误信息中写入 API Key、访问令牌或其他敏感数据。
• 需要外部数据时，请由应用侧调用已授权服务，并将结果作为 tool message 回传。

Q&A#

Q: kimi-k3 请求返回 404，如何处理？#

执行 GET https://api.unigateway.ai/v1/models，确认返回列表中存在精确 ID kimi-k3；检查 API Key 的模型白名单和账户权限。调整配置后重新查询模型列表，再使用实时返回的 ID 请求。

Q: 工具调用返回 400，如何处理？#

检查 tools 是否在请求顶层，函数是否包含 name、description 和 JSON Schema parameters，并确认每个 tool_call_id 与返回的工具调用 ID 一致。Kimi K3 支持 auto、none、required 和指定单个函数；函数名称必须与工具定义完全一致。多轮调用时必须原样回传完整 assistant message。

Q: 图像没有被识别，如何排查？#

确认 messages[].content 是对象数组；图像使用 base64 data URL；SVG 以文本输入；请求 Body 小于 100 MB 且格式受支持。修正后重新发送请求。

Q: 为什么没有命中上下文缓存？#

确认同一逻辑会话复用了相同的 X-Session-Id，相邻请求的长前缀完全一致，并且上一请求的 prompt 超过 256 tokens。不要在前缀中插入动态时间戳、随机值或频繁变化的工具定义；检查 usage.prompt_tokens_details.cached_tokens，然后重新验证。