ModelFold Docs

简体中文

English

简体中文

English

Appearance

Kimi K3 ​

本页由 ModelFold 文档站根据上游官方 OpenAPI 文档同步生成。接口路径、参数、示例与官方保持一致；品牌与 API 域名已替换为 ModelFold。

接口 ​

POST /openai/v1/responses

完整 URL: https://ai.modelfold.online/openai/v1/responses

鉴权：所有请求都需要 Authorization: Bearer <API_KEY> 请求头。

WARNING

⚠️ 仅支持对话调用

该模型目前仅支持对话调用，暂未适配 Agent 场景。若将其接入 Agent 使用，可能会出现请求报错或结果异常。

Kimi K3 是兼容 OpenAI Responses 协议的端点，支持对话、工具调用、图片输入、流式输出与思考，上下文窗口 1M tokens。

  • 思考 — 默认开启思考， reasoning.effort 可取 low / medium / high 。
  • 图片输入 — 支持在单条消息中混合文本和图片。
  • 工具调用 — 支持自定义函数调用，并可将回答约束为 JSON。
  • 统一端点 — 使用统一的 /openai/v1/responses 端点， model 参数设置为 kimi-k3 。

思考 ​

模型默认会思考。reasoning.effort 越高，思考越充分，延迟也可能更高。

  • low：更快
  • medium：均衡
  • high：更充分，适合复杂问题

不传时由模型自行决定。思考摘要只用于展示，不需要作为输入回传。

WARNING

本模型不支持联网搜索，传入 web_search 等工具会被忽略。

工具与输入 ​

基础对话（流式）

json
{
  "model": "kimi-k3",
  "stream": true,
  "input": "用一句话介绍北京"
}

多轮对话 + 系统指令（非流式）

json
{
  "model": "kimi-k3",
  "stream": false,
  "instructions": "只用英文回答",
  "input": [
    { "role": "user", "content": "我叫小明" },
    { "role": "assistant", "content": "Hi Xiaoming." },
    { "role": "user", "content": "我叫什么？" }
  ]
}

设置思考深度

json
{
  "model": "kimi-k3",
  "stream": true,
  "reasoning": { "effort": "high" },
  "input": "9.11 和 9.9 哪个大？"
}

函数调用

声明模型可调用的函数，仅支持 function 类型。传入 tools 后，将 tool_choice 设为 auto 可由模型决定是否调用；传入对象可指定某一个函数。未传 tools 时不要传 tool_choice。

json
{
  "model": "kimi-k3",
  "stream": false,
  "input": "上海现在天气怎么样？",
  "tool_choice": "auto",
  "tools": [
    {
      "type": "function",
      "name": "get_weather",
      "description": "查询城市当前天气",
      "parameters": {
        "type": "object",
        "properties": {
          "city": { "type": "string", "description": "城市名" }
        },
        "required": ["city"],
        "additionalProperties": false
      }
    }
  ]
}

回传执行结果

模型会返回一个 function_call。执行完函数后，把它和你的 function_call_output 一并追加到 input，两者通过 call_id 配对：

json
{
  "model": "kimi-k3",
  "stream": false,
  "tools": [
    {
      "type": "function",
      "name": "get_weather",
      "description": "查询城市当前天气",
      "parameters": {
        "type": "object",
        "properties": {
          "city": { "type": "string", "description": "城市名" }
        },
        "required": ["city"],
        "additionalProperties": false
      }
    }
  ],
  "input": [
    { "role": "user", "content": "北京现在天气怎么样？" },
    {
      "type": "function_call",
      "call_id": "call_6102a526bdda4ebf8e982aa3",
      "name": "get_weather",
      "arguments": "{\"city\":\"北京\"}"
    },
    {
      "type": "function_call_output",
      "call_id": "call_6102a526bdda4ebf8e982aa3",
      "output": "{\"temp_c\":21,\"condition\":\"晴\"}"
    }
  ]
}

JSON 输出

设置 text.format 可将回答约束为 JSON：

json
{ "text": { "format": { "type": "json_object" } } }

改用 json_schema 则可按你自定义的 schema 校验回答。

json
{
  "model": "kimi-k3",
  "stream": false,
  "input": "给出东京的信息",
  "text": {
    "format": {
      "type": "json_schema",
      "name": "city_info",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "city": { "type": "string" },
          "country": { "type": "string" }
        },
        "required": ["city", "country"],
        "additionalProperties": false
      }
    }
  }
}

图片输入

在同一条消息里混合 input_image 与 input_text 片段。image_url 可以是公网可访问的图片 URL，也可以是 data:image/{格式};base64,{编码}：

json
{
  "model": "kimi-k3",
  "stream": false,
  "input": [
    {
      "role": "user",
      "content": [
        { "type": "input_text", "text": "这张图里有什么？" },
        { "type": "input_image", "image_url": "https://example.com/cat.png" }
      ]
    }
  ]
}

错误处理 ​

请检查响应体，不要只看 HTTP 状态码。错误有两种形态：{"code": ..., "msg": "..."}（如 401 API key 无效、402 积分不足、429 频率超限；HTTP 状态可能仍为 200），或 {"error": {"type": "...", "message": "..."}}。

请求参数 ​

请求体 (application/json) ​

参数类型必填说明
modelstring是目标模型名称。可选值：kimi-k3。 可选值：kimi-k3。 示例：kimi-k3。
input`stringarray<objectobject
instructionsstring否给模型的系统指令，作为 system 消息插入在 input 之前。 示例：只用中文回答。
streamboolean否当为真时，响应会以服务器发送事件的形式实时流式传输。当为假时，完成之后会一次性返回完整的响应。默认值为真。 默认值：true。 示例：true。
reasoningobject否模型推理配置。默认开启思考。
  reasoning.effortstring否推理力度级别。更高的取值会带来更充分的推理，但可能增加延迟。可取 low、medium、high。不传时由模型自行决定。 可选值：low / medium / high。 示例：low。
toolsarray&lt;object&gt;否可选，模型可以调用的工具数组。仅支持 function 类型。传入 web_search 等内置工具会被忽略。
  tools[].typestring是工具类型。固定为 function。
  tools[].namestring是函数名称。模型发起调用时会原样返回。 示例：get_weather。
  tools[].descriptionstring否函数的用途说明。帮助模型判断何时调用该函数。 示例：查询城市当前天气。
  tools[].parametersobject是函数参数定义，JSON Schema 对象形式。
  tools[].strictboolean否是否严格按 parameters 生成调用参数。
tool_choice`stringobject`否
textobject否输出格式配置。
  text.format`objectobjectobject`

请求示例 ​

bash
curl -X POST "https://ai.modelfold.online/openai/v1/responses" \
  -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "kimi-k3",
  "stream": true,
  "input": "用一句话介绍北京"
}'
json
{
  "model": "kimi-k3",
  "stream": true,
  "input": "用一句话介绍北京"
}

响应 ​

200 — 请求成功。stream=true（默认）返回 text/event-stream；stream=false 返回 application/json。前置校验失败同样返回 HTTP 200，此时请以 code 判断。 ​

文本回复（stream=false）

json
{
  "id": "resp_551f7700-da28-4b8d-b831-9a675b85e73a",
  "object": "response",
  "created_at": 1790128550,
  "status": "completed",
  "model": "moonshotai/kimi-k3",
  "output": [
    {
      "type": "reasoning",
      "id": "rs_b1beab9c6ba54a7598441ed82d771f89",
      "status": "completed",
      "summary": [
        {
          "type": "summary_text",
          "text": "用户希望用一句话介绍北京……"
        }
      ]
    },
    {
      "type": "message",
      "id": "msg_347976f56b104ab291ebcc068164502c",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "annotations": [],
          "text": "北京是中国的首都，一座拥有三千多年建城史的历史文化名城，既承载着故宫、长城等千年古都的厚重底蕴，又展现着现代化国际大都市的蓬勃活力。"
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 92,
    "output_tokens": 341,
    "total_tokens": 433,
    "output_tokens_details": {
      "reasoning_tokens": 291
    }
  },
  "credits_consumed": 1.08
}

函数调用（stream=false）

json
{
  "id": "resp_4b5fff52-b406-4b34-9ca5-144960efa291",
  "object": "response",
  "created_at": 1790142133,
  "status": "completed",
  "model": "moonshotai/kimi-k3",
  "output": [
    {
      "type": "reasoning",
      "id": "rs_f7190261f68f4640bda70ff51778d3a1",
      "status": "completed",
      "summary": [
        {
          "type": "summary_text",
          "text": "用户询问上海现在的天气，调用 get_weather 即可。"
        }
      ]
    },
    {
      "type": "function_call",
      "id": "fc_ce486f4cebab4ae2b4b8d200ce34086a",
      "status": "completed",
      "name": "get_weather",
      "arguments": "{\"city\": \"上海\"}",
      "call_id": "call_6102a526bdda4ebf8e982aa3"
    }
  ],
  "usage": {
    "input_tokens": 174,
    "output_tokens": 61,
    "total_tokens": 235,
    "output_tokens_details": {
      "reasoning_tokens": 11
    }
  },
  "credits_consumed": 0.29
}

前置校验失败：积分不足

json
{
  "code": 402,
  "msg": "Credits insufficient : Your current balance isn’t enough to run this request. Please top up to continue.",
  "data": null
}

前置校验失败：API Key 无效

json
{
  "code": 401,
  "msg": "The api key does not exist.",
  "data": null
}

前置校验失败：请求过于频繁

json
{
  "code": 429,
  "msg": "Your call frequency is too high. Please try again later.",
  "data": null
}

图片无法下载

json
{
  "error": {
    "type": "server_error",
    "message": "Cannot download image [image-url] ...",
    "param": null,
    "code": null
  }
}

生成失败

json
{
  "error": {
    "type": "server_error",
    "message": "Server exception, please try again later",
    "param": null,
    "code": null
  }
}

服务维护中

json
{
  "error": {
    "type": "server_error",
    "message": "The server is currently being maintained, please try again later~",
    "param": null,
    "code": null
  }
}

400 — 请求被模型拒绝，如图片链接无法下载。 ​

参数类型必填说明
errorobject否错误详情。
  error.typestring否错误类型。 示例：server_error。
  error.messagestring否错误信息。
  error.paramstring否出错的参数，通常为 null。
  error.codestring否错误码，通常为 null。
json
{
  "error": {
    "type": "server_error",
    "message": "A serene mountain landscape at sunrise",
    "param": "",
    "code": ""
  }
}

429 — 服务容量已满，请稍后重试。 ​

参数类型必填说明
errorobject否错误详情。
  error.typestring否错误类型。 示例：server_error。
  error.messagestring否错误信息。
  error.paramstring否出错的参数，通常为 null。
  error.codestring否错误码，通常为 null。
json
{
  "error": {
    "type": "server_error",
    "message": "A serene mountain landscape at sunrise",
    "param": "",
    "code": ""
  }
}

500 — 生成失败。 ​

参数类型必填说明
errorobject否错误详情。
  error.typestring否错误类型。 示例：server_error。
  error.messagestring否错误信息。
  error.paramstring否出错的参数，通常为 null。
  error.codestring否错误码，通常为 null。
json
{
  "error": {
    "type": "server_error",
    "message": "A serene mountain landscape at sunrise",
    "param": "",
    "code": ""
  }
}

502 — 服务暂时不可用，请稍后重试。 ​

参数类型必填说明
errorobject否错误详情。
  error.typestring否错误类型。 示例：server_error。
  error.messagestring否错误信息。
  error.paramstring否出错的参数，通常为 null。
  error.codestring否错误码，通常为 null。
json
{
  "error": {
    "type": "server_error",
    "message": "A serene mountain landscape at sunrise",
    "param": "",
    "code": ""
  }
}

ModelFold — 一个 API，接入所有主流 AI 模型。

© 2026 ModelFold