联网搜索 Basic

POST

tools

联网搜索 Basic

curl --request POST \
  --url https://api.moonshot.cn/v1/tools/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "text_query": "<string>"
}
'

import requests

url = "https://api.moonshot.cn/v1/tools/search"

payload = { "text_query": "<string>" }
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({text_query: '<string>'})
};

fetch('https://api.moonshot.cn/v1/tools/search', 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/v1/tools/search",
  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([
    'text_query' => '<string>'
  ]),
  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/v1/tools/search"

	payload := strings.NewReader("{\n  \"text_query\": \"<string>\"\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/v1/tools/search")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"text_query\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.moonshot.cn/v1/tools/search")

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  \"text_query\": \"<string>\"\n}"

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

{
  "search_results": [
    {
      "authority": "<string>",
      "date": "<string>",
      "icon": "<string>",
      "mime": "<string>",
      "site_name": "<string>",
      "snippet": "<string>",
      "text": "<string>",
      "title": "<string>",
      "url": "<string>"
    }
  ]
}

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

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

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

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

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

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

发起一次网页搜索，返回标题、摘要、站点、链接等结构化搜索结果列表，适用于需要自行编排搜索逻辑的 Agent 应用。

调用示例

import os
import requests

api_key = os.environ.get("MOONSHOT_API_KEY")
url = "https://api.moonshot.cn/v1/tools/search"

response = requests.post(
    url,
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "text_query": "Kimi K2 模型 发布",
        "limit": 5,
        "timeout_seconds": 10,
    },
)
print(response.json())

curl https://api.moonshot.cn/v1/tools/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MOONSHOT_API_KEY" \
  -d '{"text_query": "Kimi K2 模型 发布", "limit": 5, "timeout_seconds": 10}'

const apiKey = process.env.MOONSHOT_API_KEY;

async function main() {
    const response = await fetch("https://api.moonshot.cn/v1/tools/search", {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
            Authorization: `Bearer ${apiKey}`,
        },
        body: JSON.stringify({
            text_query: "Kimi K2 模型 发布",
            limit: 5,
            timeout_seconds: 10,
        }),
    });
    const data = await response.json();
    console.log(data);
}

main();

响应字段说明

字段	类型	说明
`search_results`	array[object]	搜索结果列表；无结果时为空数组
`search_results[].authority`	string	来源权威性等级
`search_results[].date`	string	搜索结果日期
`search_results[].icon`	string	站点图标 URL
`search_results[].mime`	string	内容 MIME 类型
`search_results[].site_name`	string	站点名称
`search_results[].snippet`	string	搜索结果摘要
`search_results[].text`	string	网页正文内容；`include_content=true` 时返回，为 false 时为空字符串
`search_results[].title`	string	搜索结果标题
`search_results[].url`	string	搜索结果链接

以上字符串字段在无数据时返回空字符串。响应示例

{
    "search_results": [
        {
            "authority": "S",
            "date": "2026-06-01",
            "icon": "https://platform.kimi.com/favicon.ico",
            "mime": "text/html",
            "site_name": "Kimi API 开放平台",
            "snippet": "Kimi API 开放平台文档入口。",
            "text": "",
            "title": "API 概述 - Kimi API 开放平台",
            "url": "https://platform.kimi.com/docs/api/overview"
        }
    ]
}

通用响应头

响应头	说明
`X-Msh-Track-Id`	请求 ID；请求携带同名头时沿用，否则由服务端生成。排查问题时请提供该 ID
`X-Msh-Chat-Id`	会话 ID，固定为 `toolgw-{X-Msh-Track-Id}`；排查问题时请一并提供

以上两个响应头在所有响应（包括错误响应）中均会携带。

错误码说明

HTTP 状态码	error.type	典型 message	说明
400	`invalid_request`	`invalid request body`	请求体不是合法 JSON
400	`invalid_request`	`text_query is required`	缺少搜索查询文本
400	`invalid_request`	`timeout_seconds must be less than or equal to 60`	`timeout_seconds` 取值范围为 1-60
400	`invalid_request`	`limit must be between 1 and 20`	`limit` 取值范围为 1-20
401	-	无错误响应体	API Key 缺失或无效
403	-	无错误响应体	账号未激活或已停用
408	`client_canceled`	`client canceled the request`	客户端在服务端返回前断开连接
429	`rate_limited`	`project qps limit exceeded`	触发频率或并发限制；响应头携带 `X-RateLimit-Limit`、`X-RateLimit-Remaining`，触发每秒请求数限制时还携带 `X-RateLimit-Reset`
429	`rate_limit_unavailable`	`rate limit store unavailable`	限速服务暂时不可用，请稍后重试
500	`internal_error`	内部错误原文	服务内部错误，请稍后重试；若持续出现，请携带 `X-Msh-Track-Id` 联系支持团队
502	`upstream_failed`	`upstream service failed`	服务暂时不可用，请稍后重试
504	`timeout`	`request timeout`	搜索超时；可调大 `timeout_seconds` 或精简查询后重试

计费说明：请求成功（HTTP 200）且 search_results 非空时，计费一次；请求失败或未返回结果时不计费。具体价格详见联网搜索定价。

授权

Authorization

string

header

必填

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

请求体

application/json

text_query

string

必填

搜索查询文本，不能为空。

timeout_seconds

integer

搜索超时时间，单位秒，取值范围 1-60。不传则不设置单独超时。

必填范围: 1 <= x <= 60

limit

integer

默认值:5

最多返回结果数，默认 5，取值范围 1-20。

必填范围: 1 <= x <= 20

include_content

boolean

默认值:false

是否在结果项 text 中返回网页正文，默认 false。

响应

搜索结果

search_results

object[]

必填

搜索结果列表；无结果时为空数组。

Show child attributes

联网搜索 Basic

curl --request POST \
  --url https://api.moonshot.cn/v1/tools/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "text_query": "<string>"
}
'

import requests

url = "https://api.moonshot.cn/v1/tools/search"

payload = { "text_query": "<string>" }
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({text_query: '<string>'})
};

fetch('https://api.moonshot.cn/v1/tools/search', 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/v1/tools/search",
  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([
    'text_query' => '<string>'
  ]),
  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/v1/tools/search"

	payload := strings.NewReader("{\n  \"text_query\": \"<string>\"\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/v1/tools/search")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"text_query\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.moonshot.cn/v1/tools/search")

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  \"text_query\": \"<string>\"\n}"

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

{
  "search_results": [
    {
      "authority": "<string>",
      "date": "<string>",
      "icon": "<string>",
      "mime": "<string>",
      "site_name": "<string>",
      "snippet": "<string>",
      "text": "<string>",
      "title": "<string>",
      "url": "<string>"
    }
  ]
}

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

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

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

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

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

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

使用 API

API Reference

工具接口

文件接口

批处理接口

托管智能体 Beta

授权

请求体

响应