# 豆包搜索 Global 版

> 通用

提交豆包搜索 Global 版请求。`model` 固定为 `doubao-web-search-global`，其余字段为豆包原生入参（大驼峰），原样透传。

## 请求地址

`POST https://api.modelverse.cn/v1/web_search`

## 请求体

## 响应

- **200** — 豆包 Global 原生响应。HTTP 200 且 `Error.Code` 为空且 `Result.ErrorCode` 为 0 才算成功。
- **default** — 错误响应（网关侧参数/鉴权错误或上游非 200）。

## OpenAPI 定义

```json
{
  "openapi": "3.1.0",
  "x-language": "zh-CN",
  "info": {
    "title": "豆包搜索 Global 版接口文档",
    "version": "1.0.0",
    "description": "这是 ModelVerse 上 **豆包搜索 Global 版** 联网搜索模型的接口文档。\n统一入口 `POST /v1/web_search`，通过请求体中的 `model` 字段选路（转发前被剥离）。\n其余字段为豆包搜索原生参数（大驼峰命名），**原样透传、原样返回，不做归一化**。响应为非流式。\n⚠️ Global 版与 Custom 版请求/响应字段完全不同（`DocCount` + `Documents[]`，而非 `Count` + `WebResults[]`）。\n计费：一次成功调用计 1 次；HTTP 200 且 `ResponseMetadata.Error.Code` 为空且 `Result.ErrorCode` 为 0 才算成功，否则不计费。\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API endpoint."
    }
  ],
  "tags": [
    {
      "name": "Web Search",
      "description": "豆包搜索 Global 版联网搜索。"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/web_search": {
      "post": {
        "tags": [
          "Web Search"
        ],
        "operationId": "createDoubaoWebSearchGlobal",
        "summary": "豆包搜索 Global 版",
        "description": "提交豆包搜索 Global 版请求。`model` 固定为 `doubao-web-search-global`，其余字段为豆包原生入参（大驼峰），原样透传。\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DoubaoGlobalRequest"
              },
              "examples": {
                "globalSearch": {
                  "summary": "网页搜索",
                  "value": {
                    "model": "doubao-web-search-global",
                    "Query": "北京周边游玩景点推荐",
                    "DocCount": 2,
                    "MaxSnippetLength": 500,
                    "MaxImageCountPerDoc": 3
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "豆包 Global 原生响应。HTTP 200 且 `Error.Code` 为空且 `Result.ErrorCode` 为 0 才算成功。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DoubaoGlobalResponse"
                },
                "examples": {
                  "success": {
                    "summary": "成功响应（节选）",
                    "value": {
                      "ResponseMetadata": {
                        "RequestId": "...",
                        "Error": {
                          "Code": "",
                          "Message": ""
                        }
                      },
                      "Result": {
                        "TotalDocCount": 2,
                        "Documents": [
                          {
                            "Rank": 1,
                            "Url": "https://...",
                            "Title": "...",
                            "Snippet": [
                              {
                                "Type": "text",
                                "Text": "..."
                              }
                            ],
                            "DocumentInfo": {
                              "ContentCharCount": 1234,
                              "ContentTokenCount": 456,
                              "Filetype": "webpage",
                              "PublishTime": "2026-01-01"
                            },
                            "HostInfo": {
                              "Hostname": "...",
                              "IconUrl": "https://...",
                              "AuthorityLevel": "high"
                            }
                          }
                        ],
                        "ErrorCode": 0,
                        "ErrorMsg": ""
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "错误响应（网关侧参数/鉴权错误或上游非 200）。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebSearchErrorResponse"
                },
                "examples": {
                  "error": {
                    "$ref": "#/components/examples/WebSearchError"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "平台下发的 API Key，通过 `Authorization: Bearer <API Key>` 传入。"
      }
    },
    "schemas": {
      "DoubaoGlobalRequest": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "model",
          "Query"
        ],
        "properties": {
          "model": {
            "type": "string",
            "const": "doubao-web-search-global",
            "description": "模型选路标识，固定为 `doubao-web-search-global`，转发前被剥离。"
          },
          "Query": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "搜索词，1–100 字符。"
          },
          "SearchType": {
            "type": "string",
            "default": "web",
            "description": "搜索类型，默认 `web`。"
          },
          "DocCount": {
            "type": "integer",
            "maximum": 20,
            "description": "返回结果数，≤ 20，默认 web 10 / image 5。"
          },
          "MaxSnippetLength": {
            "type": "integer",
            "maximum": 3000,
            "description": "摘要最大长度，默认 500，最大 3000。"
          },
          "MaxImageCountPerDoc": {
            "type": "integer",
            "maximum": 10,
            "description": "每文档最大图片数，默认 3，最多 10。"
          },
          "Filter": {
            "$ref": "#/components/schemas/DoubaoGlobalFilter"
          },
          "ImageFilter": {
            "type": "object",
            "additionalProperties": true,
            "description": "图片尺寸/宽高比过滤。"
          }
        }
      },
      "DoubaoGlobalFilter": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "IcpHostOnly": {
            "type": "boolean",
            "description": "仅返回有 ICP 备案的站点。"
          }
        }
      },
      "DoubaoGlobalResponse": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "ResponseMetadata": {
            "$ref": "#/components/schemas/DoubaoResponseMetadata"
          },
          "Result": {
            "$ref": "#/components/schemas/DoubaoGlobalResult"
          }
        }
      },
      "DoubaoResponseMetadata": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "RequestId": {
            "type": "string",
            "description": "请求唯一标识。"
          },
          "Error": {
            "$ref": "#/components/schemas/DoubaoError"
          }
        }
      },
      "DoubaoError": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "Code": {
            "type": "string",
            "description": "业务错误码，成功时为空字符串。"
          },
          "Message": {
            "type": "string",
            "description": "业务错误描述，成功时为空字符串。"
          }
        }
      },
      "DoubaoGlobalResult": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "TotalDocCount": {
            "type": "integer",
            "description": "返回文档总数。"
          },
          "Documents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DoubaoGlobalDocument"
            },
            "description": "文档结果列表。"
          },
          "ErrorCode": {
            "type": "integer",
            "description": "业务错误码，成功时为 0。"
          },
          "ErrorMsg": {
            "type": "string",
            "description": "业务错误描述，成功时为空字符串。"
          }
        }
      },
      "DoubaoGlobalDocument": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "Rank": {
            "type": "integer",
            "description": "排序位次。"
          },
          "Url": {
            "type": "string",
            "format": "uri",
            "description": "文档地址。"
          },
          "Title": {
            "type": "string",
            "description": "文档标题。"
          },
          "Snippet": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            },
            "description": "摘要片段列表，元素含 `Type`（text/image）、`Text`、`Image` 等。"
          },
          "DocumentInfo": {
            "type": "object",
            "additionalProperties": true,
            "description": "文档信息，含 ContentCharCount、ContentTokenCount、Filetype、PublishTime。"
          },
          "HostInfo": {
            "type": "object",
            "additionalProperties": true,
            "description": "站点信息，含 Hostname、IconUrl、AuthorityLevel。"
          }
        }
      },
      "WebSearchErrorResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/WebSearchError"
          }
        }
      },
      "WebSearchError": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "message",
          "type",
          "code",
          "param"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "错误说明。"
          },
          "type": {
            "type": "string",
            "description": "错误类型。",
            "examples": [
              "invalid_request_error"
            ]
          },
          "code": {
            "type": "string",
            "description": "机器可读的错误码。",
            "examples": [
              "error_code"
            ]
          },
          "param": {
            "type": "string",
            "description": "请求 ID，用于反馈或排查错误原因。"
          }
        }
      }
    },
    "examples": {
      "WebSearchError": {
        "summary": "标准 JSON 错误响应",
        "value": {
          "error": {
            "message": "错误描述信息",
            "type": "invalid_request_error",
            "code": "error_code",
            "param": "<请求 ID，用于反馈或排查错误原因>"
          }
        }
      }
    }
  }
}
```