Generative responses
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 a query, you need a service account with the search-api.executor
role and a relevant API key you created. To authenticate successfully, provide the folder ID and API key of the service account in each query.
Query format
Each query seeking a generative response must contain a JSON
{
"messages": [
{
"content": "<text_of_message_1>",
"role": "user"
},
{
"content": "<model_response_1>",
"role": "assistant"
},
{
"content": "<text_of_message_2>",
"role": "user"
},
{
"content": "<model_response_3>",
"role": "assistant"
},
...
{
"content": "<text_of_message_n>",
"role": "user"
}
],
"site": "<website_URL_to_search>",
"host": "<host_to_search>"
}
Query parameters
-
messages
: A single search query or a search query with context in the form of chat messages exchanged 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 that the message is sent by the user, and thecontent
field contains the user's query.assistant
: Means that 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.,yandex.cloud/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. Besides, you cannot specify the exact path to the search area in thehost
field. -
url
: Restricts the search to a specific page, e.g.,yandex.cloud/docs/search-api/pricing
.Note
The
host
field has priority over thesite
field, andurl
has priority overhost
. If you provide all the three parameters in your query, the search will be limited to theurl
value and ignore thehost
andsite
values.
Request body example:
{
"messages": [
{
"content": "How much does it cost to use Search API?",
"role": "user"
}
],
"site": "yandex.cloud",
"host": "yandex.cloud/docs",
"url": "yandex.cloud/docs/search-api/pricing"
}
Submitting a query
To submit a query, use the cURL
export FOLDER-ID=<folder_ID>
export API-KEY=<API_key>
curl -X POST \
-H "Authorization: Api-Key ${API-KEY}" \
-d "@<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 it cost to use Search API?",
"role": "user"
}
],
"site": "https://yandex.cloud/ru/docs/"
}
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>"
],
"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. -
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 collection of bullets with various data. -
search_reqid
: Unique query ID in Yandex Search. -
reqid
: Unique Search API query ID.
Example of a generative response with website limitation:
{
"message": {
"content": "The cost of using Search API is based on the number of search queries per month**. [1]\n\n**Cost per 1,000 queries**, including VAT:\n\n* For night-time queries, first 1,000 queries per month: free of charge. [1]\n\n* Night-time queries in excess of 1,000 queries per month: ₽360. [1]\n\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\nTo request a change in quotas, contact technical support or your account manager. [1]",
"role": "assistant"
},
"links": [
"https://yandex.cloud/ru/docs/search-api/pricing",
"https://yandex.cloud/ru/docs/api-gateway/pricing",
"https://yandex.cloud/ru/docs/monitoring/pricing",
"https://yandex.cloud/ru/docs/ydb/pricing/ru-docapi",
"https://yandex.cloud/ru/docs/billing/concepts/serverless-free-tier"
],
"final_search_query": "search api pricing",
"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.