本文档介绍豆包搜索Global版接口的输入输出参数。调用该接口可获取搜索词相关的搜索结果，您可根据这些数据适配项目使用。

Global版仅支持按量后付费调用，不支持订阅套餐调用；

查看搜索版本差异说明；

接口限流：账号维度，默认 10 QPS，接入方可根据实际需要提工单扩容。（Global版和Custom版的并发限流相互独立）

免费额度：每个火山账号每月可免费调用500次联网搜索（额度与Custom版共用，不区分SearchType、付费类型），无论是否开通付费都将被优先消耗；

认证方式

提供 API Key 一种接入方式（不支持TOP网关接入）。

获取API Key

按量计费（后付费）：登陆并进入联网搜索控制台 - API Key管理 - 按量后付费；

在弹出的名称文本框中填写 API Key 名称，单击创建。

签名构造

API Key 签名鉴权方式要求在 HTTP 请求 header 中按如下方式添加 Authorization:

我们提供postman、python的demo文件供您使用，填写APIKEY信息后可直接发起调用

apikey方式访问global_search.zip

接口详情

URL

URL	https://open.feedcoopapi.com/search_api/global_search
Method	POST
Content-Type	application/json
Authorization	Bearer ${APIKey}

请求 Request

文搜文

字段名（一级）	字段名（二级）	类型	必须	默认值	说明
Query		String	是	-	用户搜索query，1~100个字符(过长会截断)，不支持多词搜索
SearchType		String	是	web	搜索类型，web 为文搜，未传时按 web 处理。
EnableWaiting		Boolean	否	false	是否开启队列模式 false：默认，不开启队列模式，并发量受到QPS限制； true：开启队列模式，并发超出QPS的请求进入队列按序消费；
MaxWaitTime		Number	否	5000	队列模式开启后，超出QPS限制的请求在队列中等待的最大时间（毫秒），最大10000（毫秒），默认5000（毫秒）
DocCount		Number	否	10	返回结果条数，最多20条，默认10条数量增加会增加搜索耗时不等同于响应中的 TotalDocCount
MaxSnippetLength		Number	否	500	单个摘要片段的最大tokens，传入值 > 0 时生效，最大3000，推荐1000以内
MaxImageCountPerDoc		Number	否	3	单条搜索结果最多返回的图片数量，传入值 > 0 时生效，最多10个，默认3个
Filter
	IcpHostOnly	Boolean	否	false	是否限制仅在国内ICP备案的网站中搜索 false：默认，不限制 true：限制

文搜图

字段名	类型	必须	默认值	说明
Query	String	是	-	用户搜索query，1~100个字符(过长会截断)，不支持多词搜索
SearchType	String	是	web	搜索类型，image 为搜图，未传时按 web 处理
EnableWaiting	Boolean	否	false	是否开启队列模式 false：默认，不开启队列模式，并发量受到QPS限制； true：开启队列模式，并发超出QPS的请求进入队列按序消费；
MaxWaitTime	Number	否	5000	队列模式开启后，超出QPS限制的请求在队列中等待的最大时间（毫秒），最大10000（毫秒），默认5000（毫秒）
DocCount	Number	否	5	控制本次请求返回的结果数量。传入值大于 0 时生效；最大 20
ImageFilter.ShortEdgePixelMin	Number	否	-	仅 SearchType=image 生效。图片短边下限，短边为 min(width, height)；传入小于或等于 0 时不生效。
ImageFilter.ShortEdgePixelMax	Number	否	-	仅 SearchType=image 生效。图片短边上限；传入小于或等于 0 时不生效。与 ShortEdgePixelMin 同时传入且下限大于上限时，短边筛选不生效。
ImageFilter.AspectRatioMin	Number	否	-	仅 SearchType=image 生效。图片宽高比下限，定义为 height / width；传入小于或等于 0 时不生效。
ImageFilter.AspectRatioMax	Number	否	-	仅 SearchType=image 生效。图片宽高比上限，定义为 height / width；传入小于或等于 0 时不生效。

图搜图

字段名（一级）	字段名（二级）	类型	必须	默认值	说明
Query		String	否	空字符串	仅 SearchType=visual时非必填。辅助图片检索的文本query，1~100个字符(过长会截断)，不支持多词搜索，为空时仅根据图片检索
SearchType		String	是	web	搜索类型，visual为图搜，未传时按web处理
EnableWaiting		Boolean	否	false	是否开启队列模式 false：默认，不开启队列模式，并发量受到QPS限制； true：开启队列模式，并发超出QPS的请求进入队列按序消费；
MaxWaitTime		Number	否	5000	队列模式开启后，超出QPS限制的请求在队列中等待的最大时间（毫秒），最大10000（毫秒），默认5000（毫秒）
DocCount		Number	否	0	控制本次请求返回的结果数量。传入值小于或等于 0 时使用默认值 10；最大 20
ImageQuery		Object	是	-	查询图片及可选的感兴趣区域。
		Url	String	条件必填	-	查询图片 URL。必须是包含有效 Host 的 HTTP 或 HTTPS URL；与 ImageQuery.ImageBase64 必须且只能传一个。
		ImageBase64	String	条件必填	-	查询图片的纯 Base64 编码；与 ImageQuery.Url 必须且只能传一个。不可传 Data URL 前缀（如 data:image/jpeg;base64,）
		RegionOfInterest	Object	否	整张图片	指定参与检索的矩形区域；不传时使用整张图片。
		RegionOfInterest.XMin	Number	否	-	矩形左边界相对坐标，范围为 [0, 1]。
		RegionOfInterest.YMin	Number	否	-	矩形上边界相对坐标，范围为 [0, 1]。
		RegionOfInterest.XMax	Number	否	-	矩形右边界相对坐标，范围为 [0, 1]，且必须大于 XMin。
		RegionOfInterest.YMax	Number	否	-	矩形下边界相对坐标，范围为 [0, 1]，且必须大于 YMin。
MaxSnippetLength		Number	否	300	单个摘要片段的最大长度，最大为 3000。小于或等于 0 时使用默认值 300；大于 3000 时按 3000 处理。

Curl 请求示例

文搜文

文搜图

图搜图

整图检索

指定图片区域检索

响应 Response

字段名	类型	必须	说明
ResponseMetadata	Object	是	统一响应元信息
Result		否	请求成功时的搜索结果；失败时为 null

ResponseMetadata

字段名	类型	必须	说明
RequestId	String	是	请求 ID
Action	String	是	Global版此字段为空
Version	String	是	Global版此字段为空
Service	String	是	Global版此字段为空
Region	String	是	Global版此字段为空
Error	Object	否	接口层错误信息

Result

字段名	类型	必须	说明
TotalDocCount	Number	是	本次搜索可返回的总结果数，不等同于 Documents 实际返回条数。
Documents	Array[GlobalSearchDocument]	否	本次返回的结果列表，数量受 DocCount 控制。
ErrorCode	Number	是	错误码
ErrorMsg	String	是	错误信息

GlobalSearchDocument

字段名	类型	必须	说明
Rank	Number	是	排序位置（由0开始）
Url	String	否	搜索结果落地页URL
Title	String	否	搜索结果标题
Snippet	Array[GlobalSearchSnippet]	否	相关摘要： SearchType=web时，搜索结果正文中和query相关的片段，长度由Request中的 [MaxSnippetLength] 决定， SearchType=image时，返回与query相关的图片，数量上限由 Request 中的 [MaxImageCountPerDoc] 决定
DocumentInfo	GlobalSearchDocumentInfo	否	结果统计与类型信息
HostInfo	GlobalSearchHostInfo	否	站点信息，当SearchType=web时有值

GlobalSearchSnippet

字段名	类型	必须	说明
Type	String	否	摘要类型，包括：text、image
Text	String	否	文本摘要，仅 Type = text 时返回
Image	GlobalSearchSnippetImage	否	图片摘要，仅 Type = image 时返回

GlobalSearchSnippetImage

字段名	类型	必须	说明
Width	Number	否	图片宽度
Height	Number	否	图片高度
ImageUrl	String	否	图片地址
Alt	String	否	图片替代文本，当SearchType=image时有值。
ThumbnailUrl	GlobalSearchThumbnailUrl	否	仅 SearchType=image 返回。包含各尺寸缩略图地址，缺失时寸不返回。

GlobalSearchThumbnailUrl

字段名	类型	必须	说明
Tiny	String	否	极小图地址
Small	String	否	小图地址
Medium	String	否	中图地址
Large	String	否	大图地址

GlobalSearchDocumentInfo

字段名	类型	必须	说明
ContentCharCount	Number	否	正文字符数
ContentTokenCount	Number	否	正文 token 数
Filetype	String	否	搜索结果类型，包括：webpage、pdf、image
PublishTime	String	否	网页发布时间

GlobalSearchHostInfo

字段名	类型	必须	说明
Hostname	String	否	站点名
IconUrl	String	否	站点 Icon URL
AuthorityLevel	String	否	权威度描述，包括 very_high：非常权威 high：正常权威 normal：一般权威

响应示例

文搜文

文搜图

图搜图

错误请求返回示例

错误处理

错误码	说明	建议检查/处理方式
10400	通用参数错误	文搜场景下检查 Query 是否为空、图搜场景下检查 ImageQuery 是否存在；字段类型是否正确。
10403	账号或权限错误	检查 APIKey、账号信息和服务开通状态。
10408	服务未付费开通	在控制台确认是否开通付费调用（仅当搜索服务不提供每月免费额度时出现）
10409	套餐模式不支持	豆包搜索当前仅支持后付费；检查套餐模式。
10410	无可用搜索套餐	检查账号是否已开通豆包搜索套餐。
10412	搜索套餐额度不足	检查套餐额度或联系运营处理。
10500	默认内部错误	可重试；持续失败时携带 RequestId 排查。
10501	免费额度链路依赖失败	可重试；持续失败时携带 RequestId 排查。
700429	请求频率超过限制	降低请求频率后重试。
700901	APIKey 无效	检查 Authorization Header 是否为 Bearer APIKey。