Messages API

POST

anthropic

messages

Messages API

curl --request POST \
  --url https://api.moonshot.cn/anthropic/v1/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "kimi-k3",
  "messages": [
    {
      "role": "user",
      "content": "你好"
    }
  ],
  "max_tokens": 2
}
'

import requests

url = "https://api.moonshot.cn/anthropic/v1/messages"

payload = {
    "model": "kimi-k3",
    "messages": [
        {
            "role": "user",
            "content": "你好"
        }
    ],
    "max_tokens": 2
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({model: 'kimi-k3', messages: [{role: 'user', content: '你好'}], max_tokens: 2})
};

fetch('https://api.moonshot.cn/anthropic/v1/messages', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.moonshot.cn/anthropic/v1/messages",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'model' => 'kimi-k3',
    'messages' => [
        [
                'role' => 'user',
                'content' => '你好'
        ]
    ],
    'max_tokens' => 2
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.moonshot.cn/anthropic/v1/messages"

	payload := strings.NewReader("{\n  \"model\": \"kimi-k3\",\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"你好\"\n    }\n  ],\n  \"max_tokens\": 2\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.moonshot.cn/anthropic/v1/messages")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"kimi-k3\",\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"你好\"\n    }\n  ],\n  \"max_tokens\": 2\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.moonshot.cn/anthropic/v1/messages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"kimi-k3\",\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"你好\"\n    }\n  ],\n  \"max_tokens\": 2\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "type": "message",
  "role": "assistant",
  "model": "<string>",
  "content": [
    {
      "type": "thinking",
      "thinking": "<string>",
      "signature": "<string>"
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": "<string>",
  "usage": {
    "input_tokens": 123,
    "output_tokens": 123,
    "cache_read_input_tokens": 123,
    "cache_creation_input_tokens": 123,
    "cache_creation": {
      "ephemeral_5m_input_tokens": 123,
      "ephemeral_1h_input_tokens": 123
    },
    "output_tokens_details": {
      "thinking_tokens": 123
    }
  }
}

{
  "type": "error",
  "error": {
    "type": "<string>",
    "message": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>"
  }
}

{
  "type": "error",
  "error": {
    "type": "<string>",
    "message": "<string>"
  },
  "request_id": "<string>"
}

以 Anthropic Messages API 兼容的格式调用 Kimi 模型。已经在使用 Anthropic SDK、Claude Code 等工具的开发者，只需把 base URL 指向 https://api.moonshot.cn/anthropic，即可直接调用 Kimi 模型。

上下文缓存（Cache Write）

通过顶层 cache_control 控制上下文缓存的写入行为（仅顶层传入时生效，messages 消息体内的 cache_control 标记会被忽略）：

参数	类型	说明
`cache_control`	object	上下文缓存写入选项，仅顶层传入时生效；不传时本次请求只读取缓存（`5m` 档）不写入
`cache_control.type`	`"ephemeral"`	缓存类型，固定为 `ephemeral`
`cache_control.ttl`	`"5m"` \| `"1h"`	缓存写入的有效期，仅支持 `5m`、`1h` 两档（默认 `5m`），两档缓存相互独立

传入顶层 cache_control：将请求前缀按指定 TTL 写入缓存。
不传 cache_control：本次请求只尝试读取缓存（5m 档），不写入缓存，不产生缓存写入费用。

{
    "model": "kimi-k3",
    "cache_control": { "type": "ephemeral", "ttl": "1h" },
    "messages": [{"role": "user", "content": "你好"}]
}

行为说明

缓存以组织（org）为粒度隔离，组织之间不共享缓存。
相同前缀的请求在缓存有效期内命中后，缓存的有效期会按原 TTL 刷新；命中部分只收取缓存读取费用，不再收取缓存写入费用。
缓存写入按 TTL 分别计费，价格详见产品定价。
不支持手动清除缓存，已缓存的前缀在至少 5 分钟不活动后自动过期。

用量字段

字段	说明
`usage.input_tokens`	既未命中缓存、也未用于创建缓存条目的输入 Token 数
`usage.cache_read_input_tokens`	命中缓存的输入 Token 数（缓存读取）
`usage.cache_creation_input_tokens`	创建新缓存条目时写入缓存的输入 Token 数（缓存写入）
`usage.cache_creation.ephemeral_5m_input_tokens`	写入 `5m` 档缓存的输入 Token 数
`usage.cache_creation.ephemeral_1h_input_tokens`	写入 `1h` 档缓存的输入 Token 数

总输入 = input_tokens + cache_read_input_tokens + cache_creation_input_tokens。

本页 input_tokens 的口径与 Chat Completions / Responses API 不同：这两个 API 的 prompt_tokens / input_tokens 始终为总输入，缓存读写部分在各自的 details 字段中拆分。

Context Caching 的机制背景详见上下文缓存指南。

授权

Authorization

string

header

必填

Authorization 请求头需要一个 Bearer 令牌。使用 MOONSHOT_API_KEY 作为令牌。这是一个服务端密钥，请在 API 密钥页面生成。

请求头

X-Msh-Request-Nonce

string

客户端生成的随机 nonce（推荐使用 UUID v4），携带后即开启请求签名：Kimi API 会在响应头中返回 Msh-Request-Timestamp 与 Msh-Request-Signature，用于事后证明该请求确实由 Kimi API 处理。只允许一个非空的 Header 值；值不合法时请求照常执行，但不返回上述响应头。详见校验请求签名。

Minimum string length: 1

示例:

"7d929748-0ae6-41c2-ab5d-a186498ad721"

请求体

application/json

model

enum<string>

默认值:kimi-k3

必填

模型 ID

可用选项:

kimi-k3

messages

object[]

必填

对话消息列表。若最后一条为 assistant 消息，模型会从该消息内容之后继续生成（Partial Mode）。

Show child attributes

max_tokens

integer

必填

本次生成的最大 Token 数，必填。达到上限而未结束时 stop_reason 为 max_tokens。

必填范围: x >= 1

system

系统提示，可为字符串或 text 块数组

stream

boolean

默认值:false

是否以 Server-Sent Events 流式返回，默认 false

stop_sequences

string[]

停用词，完全匹配时停止输出，匹配到的词本身不会被输出。最多 5 个，每个不超过 32 字节。

Maximum array length: 5

tools

object[]

模型可调用的工具列表

Show child attributes

tool_choice

object

控制模型是否调用工具。auto（默认）：模型自行决定；any：强制调用任意工具；none：不调用工具。

Show child attributes

metadata

object

Show child attributes

cache_control

object

上下文缓存写入选项，仅在顶层传入时生效，messages 消息体内的 cache_control 标记会被忽略。不传时本次请求只尝试读取缓存（5m 档），不写入缓存

Show child attributes

output_config

object

输出配置：推理强度与结构化输出

Show child attributes

响应

消息响应

string

本次响应的唯一标识符

type

enum<string>

可用选项:

message

示例:

"message"

role

enum<string>

可用选项:

assistant

model

string

请求中指定的模型

content

(thinking · object | text · object | tool_use · object)[]

内容块列表，顺序为 thinking → text → tool_use

thinking
text
tool_use

Show child attributes

stop_reason

enum<string> | null

停止原因。end_turn：自然结束（含命中 stop_sequences）；max_tokens：达到 max_tokens 上限；tool_use：模型发起工具调用；refusal：触发内容安全审查。

可用选项:

end_turn,

max_tokens,

tool_use,

refusal,

null

stop_sequence

string | null

匹配到的停用词

usage

object

Token 用量

Show child attributes

Messages API

curl --request POST \
  --url https://api.moonshot.cn/anthropic/v1/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "kimi-k3",
  "messages": [
    {
      "role": "user",
      "content": "你好"
    }
  ],
  "max_tokens": 2
}
'

import requests

url = "https://api.moonshot.cn/anthropic/v1/messages"

payload = {
    "model": "kimi-k3",
    "messages": [
        {
            "role": "user",
            "content": "你好"
        }
    ],
    "max_tokens": 2
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({model: 'kimi-k3', messages: [{role: 'user', content: '你好'}], max_tokens: 2})
};

fetch('https://api.moonshot.cn/anthropic/v1/messages', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.moonshot.cn/anthropic/v1/messages",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'model' => 'kimi-k3',
    'messages' => [
        [
                'role' => 'user',
                'content' => '你好'
        ]
    ],
    'max_tokens' => 2
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.moonshot.cn/anthropic/v1/messages"

	payload := strings.NewReader("{\n  \"model\": \"kimi-k3\",\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"你好\"\n    }\n  ],\n  \"max_tokens\": 2\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.moonshot.cn/anthropic/v1/messages")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"kimi-k3\",\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"你好\"\n    }\n  ],\n  \"max_tokens\": 2\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.moonshot.cn/anthropic/v1/messages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"kimi-k3\",\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"你好\"\n    }\n  ],\n  \"max_tokens\": 2\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "type": "message",
  "role": "assistant",
  "model": "<string>",
  "content": [
    {
      "type": "thinking",
      "thinking": "<string>",
      "signature": "<string>"
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": "<string>",
  "usage": {
    "input_tokens": 123,
    "output_tokens": 123,
    "cache_read_input_tokens": 123,
    "cache_creation_input_tokens": 123,
    "cache_creation": {
      "ephemeral_5m_input_tokens": 123,
      "ephemeral_1h_input_tokens": 123
    },
    "output_tokens_details": {
      "thinking_tokens": 123
    }
  }
}

{
  "type": "error",
  "error": {
    "type": "<string>",
    "message": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>"
  }
}

{
  "type": "error",
  "error": {
    "type": "<string>",
    "message": "<string>"
  },
  "request_id": "<string>"
}

使用 API

API Reference

工具接口

文件接口

批处理接口

托管智能体 Beta

授权

请求头

请求体

响应