OpenSearch:Internet search

Service list

Service name	Service ID	Description	QPS limit
Internet search service	ops-web-search-001	A general-purpose internet search service that you can combine with a large language model (LLM) to enhance responses in private knowledge base scenarios.	3 Note To increase the QPS limit, submit a ticket.

• Get authentication credentials

  The AI Search open platform requires an API key for authentication. For instructions, see Get an API key.

• Get the service endpoint

  You can call the service via the public network or a VPC. For details, see Get the service endpoint.

Request method

POST

URL

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

• host: The service access address. You can call the API over the internet or through a VPC. For more information, see Get a service access address.

  On the API Keys page, select a workspace such as default. In the Access Endpoints section, switch between the Public API Endpoints and Private API Endpoints tabs to find the access address.

• workspace_name: The name of the workspace. For example, default.

• service_id: The built-in service ID. For example, ops-web-search-001.

Request parameters

Header parameters

Parameter	Type	Required	Description	Example
Content-Type	String	Yes	The request content type. Must be application/json.	application/json
Authorization	String	Yes	Your API key.	Bearer OS-d1**2a

Body parameters

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.	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 is in the format {"role": , "content": }. Supported roles: system, user, and assistant. system: A system-level message. If used, it must be the first element in the history list. user and assistant: The user message and the model response. These roles must alternate to reflect the conversation flow.	null
content_type	String	No	The content type of search results. snippet: A short description of the web page. summary: A text summary of the web page. May increase latency compared to snippet. mainText: The main text of the web page. Returns more characters than snippet and summary, up to 3,000 characters.	snippet

cURL example

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer " \
"http://xxxx-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/web-search/ops-web-search-001" \
-d '{
      "history": [
        {"role": "system", "content": "You are a robot assistant"},
        {"role": "user", "content": "What is the capital of Zhejiang Province?"},
        {"role": "assistant", "content": "Hangzhou"}
        ],
      "query":"What is the weather like 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 internet 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.xxx.com
result.search_result[].snippet	String	A summary 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 rank of the web page in the search results.	3
usage.search_count	Integer	The number of internet searches performed.	1
usage.rewrite_model.input_tokens	Integer	The number of input tokens used to rewrite the query.	100
usage.rewrite_model.output_tokens	Integer	The number of output tokens generated by the query rewrite.	100
usage.rewrite_model.total_tokens	Integer	The total number of tokens used for the query rewrite.	200
usage.filter_model.input_tokens	Integer	The number of input tokens used for LLM-based result filtering.	100
usage.filter_model.output_tokens	Integer	The number of output tokens generated during LLM-based result filtering.	100
usage.filter_model.total_tokens	Integer	The total number of tokens used for LLM-based result filtering.	200

Response example

Successful response

{
  "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 winds at level 2-3 tonight, easterly winds at level 2 tomorrow. Maximum temperature tomorrow is 10°C, minimum temperature tomorrow morning 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 winds at level 2-3 tonight, easterly winds at level 2 tomorrow. Maximum temperature tomorrow is 10°C, minimum temperature tomorrow morning 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's current conditions: 3°C and sunny, humidity at 66%, northwesterly winds at level 3. Daytime: 10°C, sunny. Nighttime: cloudy, 3°C. It's getting cooler, Moji Weather recommends wearing a thick coat over a wool sweater. The elderly and infirm may want to wear a woolen overcoat for additional warmth.",
          "position": 4,
          "content": "Hangzhou City Weather Forecast_Weather Query - Moji Weather\nHangzhou's current conditions: 3°C and sunny, humidity at 66%, northwesterly winds at level 3. Daytime: 10°C, sunny. Nighttime: cloudy, 3°C. It's getting cooler, Moji Weather recommends wearing a thick coat over a wool sweater. The elderly and infirm may want to wear a woolen overcoat for additional 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

If an error occurs, the response includes a code and a message that describes 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 succeeded. This status is returned even if the task failed. Check the result.status field to determine the task status.
404	BadRequest.TaskNotExist	The task does not exist.
400	InvalidParameter	The request was invalid.
500	InternalServerError	An internal error occurred.

For more information, see Status codes for AI Search Open Platform.