Generative response

Written by

Updated at December 5, 2024

Search query
Generative response
- Response features

You can use Yandex 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 Yandex Search API from your company's websites.

Note

This feature is in the Preview stage.

Currently, generative response is only available for queries submitted via the API v1.

Search query

Queries to Yandex 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 format:

{
  "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 the role value).
- role: Message sender's role. The possible values are:
  - user: Means the message is sent by the user, and the content field contains the user's query.
  - assistant: Means the message is sent by the model, and the content 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 the host 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, or url.

The host field has priority over the site field, and url has priority over host. If you provide all three parameters in your query, the search will be limited to the url value, and the host and site values will be ignored.

Request body example:

{
  "messages": [
    {
      "content": "How much does Yandex Search API cost?",
      "role": "user"
    }
  ],
  "site": "https://yandex.cloud/en/docs"
}

Submitting a query

To submit a query, use the cURL utility or Python. Before submitting your query, save the folder ID and API key of your service account to environment variables:

export FOLDER_ID=<folder_ID>
export API_KEY=<API_key>

cURL

Python 3

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 Yandex 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()