Generative response
You can use Search API text search together with YandexGPT generative AI to get a comprehensive and concise generative response to a user query. To generate such a response, the model analyzes the relevant text search results retrieved by Search API from your company's websites.
Note
This feature is in the Preview stage.
To get access to the generative response feature, fill out this form or contact your account manager.
Search query
Queries to Search API seeking a generative response are submitted using the POST method to the https://yandex.com/search/xml/generative
endpoint.
To run queries, you need a service account with the search-api.executor
role and an API key created for it. To authenticate successfully, provide the folder ID and API key of the service account in each query.
Request format
Each query seeking a generative response must contain the following request body in JSON
{
"messages": [
{
"content": "<message_1_text>",
"role": "user"
},
{
"content": "<model_1_response>",
"role": "assistant"
},
{
"content": "<message_2_text>",
"role": "user"
},
{
"content": "<model_3_response>",
"role": "assistant"
},
...
{
"content": "<message_n_text>",
"role": "user"
}
],
"site": "<website_address_for_search>",
"host": "<host_for_search>",
"url": "<page_for_search>"
}
Request parameters
-
messages
: Single search query or a search query with context in the form of chat with the model. It is specified as an array of objects, each one containing two elements:content
: Text of user query or the model's response (depending on therole
value).role
: Message sender's role. The possible values are:user
: Means the message is sent by the user, and thecontent
field contains the user's query.assistant
: Means the message is sent by the model, and thecontent
field contains the model's response.
For more information about the YandexGPT chat mode, see How to create a chat with YandexGPT.
-
site
: Restricts the search to a specific website, e.g.,yandex.cloud
.The search will target all
*.yandex.cloud/*
documents, i.e., the results will include pages with the following URLs:yandex.cloud/
subdomain.yandex.cloud/
yandex.cloud/path/
subdomain.yandex.cloud/path/
You can use the
site
field to specify the exact path to the search area, e.g.,https://yandex.cloud/en/docs
. -
host
: Restricts the search to a specific host, e.g.,yandex.cloud/
.The search will target all
yandex.cloud/*
documents, i.e., the results will include pages with the following URLs:yandex.cloud/
yandex.cloud/path/
Unlike
site
-based restrictions,host
-based restrictions do not apply to subdomains. You also cannot provide a specific path to the search area in thehost
field. -
url
: Restricts the search to a specific page, e.g.,https://yandex.cloud/en/docs/search-api/pricing
.Note
To restrict the search, you simply need to specify one of these fields in your query:
site
,host
, orurl
.The
host
field has priority over thesite
field, andurl
has priority overhost
. If you provide all three parameters in your query, the search will be limited to theurl
value, and thehost
andsite
values will be ignored.
Request body example:
{
"messages": [
{
"content": "How much does Search API cost?",
"role": "user"
}
],
"site": "https://yandex.cloud/en/docs"
}
Submitting a query
To submit a query, use the cURL
export FOLDER_ID=<folder_ID>
export API_KEY=<API_key>
curl \
--request POST \
--header "Authorization: Api-Key ${API_KEY}" \
--data "@<path_to_request_body_file>" \
"https://yandex.com/search/xml/generative?folderid=${FOLDER_ID}"
import requests
import os
SEARCH_API_GENERATIVE = f"https://ya.ru/search/xml/generative?folderid={os.getenv('FOLDER_ID')}"
def main():
headers = {"Authorization": f"Api-Key {os.getenv('API_KEY')}"}
data = {
"messages": [
{
"content": "How much does Search API cost?",
"role": "user"
}
],
"url": "https://yandex.cloud/en/docs/search-api/pricing"
}
response = requests.post(SEARCH_API_GENERATIVE, headers=headers, json=data)
if "application/json" in response.headers["Content-Type"]:
print(response.json()["message"]["content"])
for i, link in enumerate(response.json()["links"], start=1):
print(f"[{i}]: {link}")
elif "text/xml" in response.headers["Content-Type"]:
print("Error:", response.text)
else:
print("Unexpected content type:", response.text)
if __name__ == "__main__":
main()
Generative response
Search API returns a JSON format response with the following syntax:
{
"message": {
"content": "<response_text>",
"role": "assistant"
},
"links": [
"<link_to_found_document_1>",
"<link_to_found_document_2>",
...
"<link_to_found_document_n>"
],
"titles": [
"<title_of_found_document_1>",
"<title_of_found_document_2>",
...
"<title_of_found_document_n>"
],
"final_search_query": "<refined_query_text>",
"is_answer_rejected": false (true),
"is_bullet_answer": false (true),
"search_reqid" : "...",
"reqid" : "..."
}
Where:
-
content
: Text of the generative response. -
links
: Sorted list of links to documents found when processing the query which could be used by YandexGPT to generate the response. -
titles
: Sorted list of document titles. -
final_search_query
: Final text of the search query, refined by the YandexGPT model and used for the generative response. May be different from the original user query. -
is_answer_rejected
: Indicates the model's refusal to provide a response for ethical reasons:false
: Model has returned a response.true
: Model has refused to return a response.
-
is_bullet_answer
: Indicates a bullet answer where the model cannot give a proper response and returns a set of bullets with various data. -
search_reqid
: Unique query ID in Yandex Search. -
reqid
: Search API unique query ID.
Here is an example of a generative response with website limitation:
{
"message": {
"content": "The cost of using Search API **is calculated based on the number of search queries initiated within a calendar month**. [1]\n\n**Cost per 1,000 queries**, including VAT: [1]\n- Night-time queries, first 1,000 queries per month: free of charge. [1]\n- Night-time queries, over 1,000 requests per month: ₽360. [1]\n- Daytime queries: ₽480. [1]\n\nThe service has a quota of 30,000 queries per month (1,000 queries per day) for all new users. [1]\n\nPrices may differ from region to region, and payment currency depends on the legal entity the user has an agreement with. [1]",
"role": "assistant"
},
"links": [
"https://yandex.cloud/en/docs/search-api/pricing",
"https://yandex.cloud/en/docs/search-api/concepts/generative-response",
"https://yandex.cloud/en/docs/api-gateway/pricing",
"https://yandex.cloud/en/docs/functions/pricing",
"https://yandex.cloud/en/docs/ydb/pricing/ru-docapi"
],
"titles": [
"Yandex Search API pricing policy | Yandex Cloud documentation",
"Generative response | Yandex Cloud documentation",
"Yandex API Gateway pricing policy | Yandex Cloud documentation",
"Cloud Functions pricing policy | Yandex Cloud documentation",
"Rules for estimating the cost of queries to YDB via Document API | Yandex Cloud documentation"
],
"final_search_query": "Search API cost",
"is_answer_rejected": false,
"is_bullet_answer": false,
"search_reqid": "1716922280912146-404265690610183965-**************-BAL",
"reqid": "1716922280829905-8678730291785779856-********-l7leveler-***-**-***-***-BAL"
}
Response features
Based on the query and search results, Search API may include the following warnings in a generative response:
-
If no relevant documents were found:
No results found.
Please rephrase your query or ask something else. -
If Search API has found the relevant source documents but was unable to extract information:
Failed to extract the requested information from the documents. You can try opening them yourself or view the search results.
-
If Search API has found the source documents and succeeded extracting the information but is doubtful about response quality, it will preface its response with:
There is various information on this topic online. You can find its overview below.