Web search

Service list

Service name	Service ID	Description	QPS limit
Web search service	ops-web-search-001	A general-purpose web search service. Use it with a large language model (LLM) to supplement answers in private knowledge base scenarios.	3 Note To increase the QPS limit, submit a ticket.

• Obtain authentication credentials

  API calls to AI Search Open Platform require identity authentication. For instructions on obtaining credentials, see Obtain an API key.

• Obtain a service access address

  You can call the service over the internet or through a VPC. For details, see Obtain service access addresses.

Request method

POST

URL

{host}/v3/openapi/workspaces/{workspace_name}/web-search/{service_id}

• host: The service access address. For details, see Obtain service access addresses.

  On the API Keys page, select the target workspace (for example, default (default workspace)) at the top of the page. In the Access Domain section, switch between the public API domain and private API domain tabs to find the address.

• workspace_name: The name of the workspace. Example: default.

• service_id: The built-in service ID. Example: ops-web-search-001.

Request parameters

Headers

These headers are required for API key authentication.

Parameter	Type	Required	Description	Example
Content-Type	String	Yes	Request type: application/json	application/json
Authorization	String	Yes	Your API key, prefixed with Bearer .	Bearer OS-d1**2a

Body

Parameter	Type	Required	Description	Default
query	String	Yes	The search query.
query_rewrite	Boolean	No	Specifies whether to use an LLM to rewrite the query for better relevance. The default value is true.	true
top_k	Integer	No	The number of search results to return.	5
history	List	No	The conversation history between the user and the model. Each element in the list is an object with the format {"role": <role>, "content": <content>}. The role can be system, user, or assistant. system: A system-level message. It is optional, but if provided, it must be the first message in the history array. user and assistant: Represent messages from the user and the model, respectively. They must alternate in the conversation history.	null
content_type	String	No	The content type of the search results. snippet: A short description of the web page content. summary: A text summary of the web page content. This option increases latency compared to snippet.	snippet

cURL example

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
"http://xxxx-cn-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/web-search/ops-web-search-001" \
-d '{
      "history": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is the capital of Zhejiang province?"},
        {"role": "assistant", "content": "Hangzhou"}
        ],
      "query":"What is the weather in Hangzhou today?",
      "query_rewrite":true,
      "top_k":5,
      "content_type":"snippet"
}'

Response parameters

Parameter	Type	Description	Example
result.search_result	List<search_result>	The search results.
result.search_result[].title	String	The title of the web page.	Hangzhou Weather
result.search_result[].link	String	The URL of the web page.	https://www.example.com
result.search_result[].snippet	String	The snippet of the web page.	Cloudy tonight; sunny to partly cloudy tomorrow; partly cloudy to overcast the day after tomorrow.
result.search_result[].content	String	The content of the web page.	Hangzhou Weather\nCloudy tonight; sunny to partly cloudy tomorrow;
result.search_result[].position	Integer	The position of the web page in the retrieved results.	3
usage.search_count	Integer	The number of web searches performed.	1
usage.rewrite_model.input_tokens	Integer	The number of input tokens used for query rewriting.	100
usage.rewrite_model.output_tokens	Integer	The number of output tokens generated by query rewriting.	100
usage.rewrite_model.total_tokens	Integer	The total number of tokens for query rewriting.	200
usage.filter_model.input_tokens	Integer	The number of input tokens used for LLM-based filtering of search results.	100
usage.filter_model.output_tokens	Integer	The number of output tokens generated by LLM-based filtering of search results.	100
usage.filter_model.total_tokens	Integer	The total number of tokens used for LLM-based filtering of search results.	200

Response examples

Success response example

{
  "result":{
    "search_result": [
        {
          "title": "Hangzhou Weather",
          "link": "https://www.hzqx.com/pc/hztq/",
          "snippet": "Cloudy tonight; sunny to partly cloudy tomorrow; partly cloudy to overcast the day after tomorrow. Northerly wind at 2-3 levels tonight, easterly wind at 2 levels tomorrow. Max temperature tomorrow is 10°C, min temperature is 3°C, and average relative humidity is 65%.",
          "position": 3,
          "content": "Hangzhou Weather\nCloudy tonight; sunny to partly cloudy tomorrow; partly cloudy to overcast the day after tomorrow. Northerly wind at 2-3 levels tonight, easterly wind at 2 levels tomorrow. Max temperature tomorrow is 10°C, min temperature is 3°C, and average relative humidity is 65%."
        },
        {
          "title": "Hangzhou City Weather Forecast_Weather Query - Moji Weather",
          "link": "https://tianqi.moji.com/weather/china/zhejiang/hangzhou",
          "snippet": "Hangzhou current conditions: 3°C and sunny, humidity: 66%, northwest wind: level 3. Daytime: 10°C, sunny. Night: cloudy, 3°C. It's getting cool, Moji Weather suggests you wear a thick coat over your sweater. The elderly and infirm can wear a woolen overcoat for extra warmth.",
          "position": 4,
          "content": "Hangzhou City Weather Forecast_Weather Query - Moji Weather\nHangzhou current conditions: 3°C and sunny, humidity: 66%, northwest wind: level 3. Daytime: 10°C, sunny. Night: cloudy, 3°C. It's getting cool, Moji Weather suggests you wear a thick coat over your sweater. The elderly and infirm can wear a woolen overcoat for extra warmth."
        }
    ]
  },
    "usage": {
            "search_count": 1,
            "rewrite_model.input_tokens": 249,
            "rewrite_model.output_tokens": 1,
            "rewrite_model.total_tokens": 250,
            "filter_model.input_tokens": 1804,
            "filter_model.output_tokens": 216,
            "filter_model.total_tokens": 2020
    }
}

Error response example

If a request fails, the response includes code and message fields that indicate the reason for the error.

{
    "request_id": "6F33AFB6-A35C-****-AFD2-9EA16CCF4383",
    "latency": 2.0,
    "code": "InvalidParameter",
    "http_code": 400,
    "message": "JSON parse error: Cannot deserialize value of type `ImageStorage` from String \\"xxx\\"
}

Status codes

HTTP status code	Error code	Description
200	-	The request was successful.
404	BadRequest.TaskNotExist	The task does not exist.
400	InvalidParameter	The request is invalid.
500	InternalServerError	An internal server error occurred.

For a complete list of status codes, see AI Search Open Platform status codes.