> For the complete documentation index, see [llms.txt](https://docs.avis.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avis.net/vi/tai-lieu-api/endpoints/audio-generation.md). # Tạo âm thanh Module âm thanh có hai sản phẩm riêng dưới `/audio`, dùng chung danh mục giọng đọc và các endpoint tra cứu (poll/pending/history). Job của cả hai sản phẩm được trả về cùng nhau và phân biệt bằng trường `product`. | Sản phẩm | Endpoint gửi | Endpoint ước tính | Mô hình | | ------------------------- | ---------------------------------------------- | ------------------------------------------------------- | ------------------------------ | | Text-to-Speech | `POST /api/v1/audio/text-to-speech` | `POST /api/v1/audio/text-to-speech/estimate` | `seed-tts-1.0`, `seed-tts-2.0` | | Generation With Reference | `POST /api/v1/audio/generation-with-reference` | `POST /api/v1/audio/generation-with-reference/estimate` | `seed-audio-1.0-multilingual` | Cả hai sản phẩm đều xử lý bất đồng bộ theo job, tương tự tạo video. Request gửi trả về `202 Accepted` cùng `{ generationId }`. Gọi định kỳ `GET /api/v1/audio/generations/:generationId` để kiểm tra cho đến khi `status` chuyển sang trạng thái kết thúc (`succeeded` hoặc `failed`). ### Khi nào dùng cái nào * **Text-to-Speech** tạo âm thanh bằng một giọng cố định trong danh mục (`voiceType`, lấy từ `GET /audio/voices`): bạn gửi văn bản thuần để giọng đó đọc. Sản phẩm này không hỗ trợ âm thanh tham chiếu, hình ảnh hoặc nhân bản giọng nói. Đổi lại, sản phẩm có các tùy chọn điều khiển cách đọc không có trong Generation With Reference: `pitch`, `silenceDuration`, `enableLanguageDetector`/`explicitLanguage` và bộ lọc markdown/emoji. * **Generation With Reference** hỗ trợ nhiều loại tham chiếu hơn. Sản phẩm này cũng có thể đọc bằng giọng trong danh mục (đặt `references: [{ speaker: ... }]`, hoặc bỏ `references` để chỉ dùng văn bản), nhân bản giọng nói từ tối đa 3 đoạn âm thanh tham chiếu (`audioUrl`/`audioData`), tạo âm thanh dựa trên hình ảnh tham chiếu và trả phụ đề theo từng từ (`enableSubtitle`). Text-to-Speech không hỗ trợ các tính năng này. Chọn Text-to-Speech nếu bạn cần đọc văn bản bằng một giọng trong danh mục và muốn điều chỉnh cách đọc. Chọn Generation With Reference nếu cần nhân bản giọng nói, dùng hình ảnh tham chiếu hoặc tạo phụ đề. ### Danh mục giọng đọc `GET /api/v1/audio/voices` Liệt kê danh mục giọng đọc TTS dùng chung. Text-to-Speech chọn giọng qua `voiceType`; Generation With Reference có thể dùng giọng `seed-tts-2.0` làm `speaker` trong `references[]`. #### Tham số query | Trường | Kiểu | Bắt buộc | Giá trị cho phép | Mô tả | | ------------ | ------ | -------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------- | | `gender` | string | Không | `male`, `female` | Lọc theo giới tính của giọng. | | `age` | string | Không | `child`, `teenager`, `adult`, `middle-age` | Lọc theo nhóm tuổi của giọng. | | `category` | string | Không | `General`, `Dubbing`, `Advertisement`, `AudioBook`, `Conversational`, `Entertainment`, `SocialMedia` | Lọc theo danh mục mục đích sử dụng. | | `language` | string | Không | Mã BCP-47, ví dụ `en-US` | Lọc các giọng hỗ trợ một ngôn ngữ cụ thể. | | `resourceId` | string | Không | `seed-tts-1.0`, `seed-tts-2.0` | Lọc theo một phiên bản mô hình TTS. | #### Các trường response | Trường | Kiểu | Mô tả | | ------------------------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `voices` | object\[] | Mảng các đối tượng giọng đọc (xem bên dưới). | | `total` | number | Tổng số giọng khớp điều kiện. | | `voices[].voiceType` | string | Mã định danh giọng. Truyền vào `voiceType` trong Text-to-Speech, hoặc vào `speaker` trong `references[]` của Generation With Reference. | | `voices[].name` | string | Tên hiển thị. | | `voices[].gender` | string | `male` hoặc `female`. | | `voices[].age` | string | `child`, `teenager`, `adult` hoặc `middle-age`. | | `voices[].categories` | string\[] | Các danh mục mục đích sử dụng. | | `voices[].languages` | object\[] | Các ngôn ngữ được hỗ trợ: `{ language, text, flag }` (tag BCP-47, văn bản mẫu, emoji cờ). | | `voices[].avatar` | string | URL ảnh đại diện. | | `voices[].trialUrl` | string | URL âm thanh mẫu (mp3). | | `voices[].description` | string | Mô tả giọng đọc. | | `voices[].resourceId` | string | `seed-tts-1.0` hoặc `seed-tts-2.0`. | | `voices[].capabilities.contextTexts` | boolean | Giọng này có hỗ trợ `contextTexts` (prompt phong cách bằng ngôn ngữ tự nhiên) hay không. Chỉ là `true` với các giọng `seed-tts-2.0`. | ### Text-to-Speech `POST /api/v1/audio/text-to-speech` Tổng hợp giọng nói từ văn bản thuần bằng giọng trong danh mục. Mô hình (`seed-tts-1.0` hoặc `seed-tts-2.0`) được xác định ngầm bởi `voiceType` đã chọn. Các giọng TTS 2.0 có tên kết thúc bằng `_uranus_bigtts`. #### Các trường request | Trường | Kiểu | Bắt buộc | Ràng buộc | Mô tả | | ------------------------ | --------- | -------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `voiceType` | string | Có | Không rỗng | Mã định danh giọng. Dùng `GET /audio/voices` để liệt kê các giá trị hợp lệ. | | `text` | string | Có | 1–1000 ký tự | Văn bản thuần cần tổng hợp. Không hỗ trợ SSML. | | `format` | string | Không | `mp3`, `ogg_opus`, `pcm` | Định dạng âm thanh đầu ra. Mặc định là `mp3`. Không hỗ trợ `wav` — mỗi chunk WAV khi stream đều có header riêng, nên buffer nối lại sẽ không phải là tệp WAV hợp lệ; hãy dùng `pcm` nếu bạn cần âm thanh không nén. | | `sampleRate` | integer | Không | `8000`, `16000`, `22050`, `24000`, `32000`, `44100`, `48000` | Tần số lấy mẫu tính bằng Hz. Mặc định là `24000`. | | `speechRate` | integer | Không | `-50` đến `100`, mặc định `0` | Tốc độ đọc. `0` = bình thường, `100` = nhanh gấp 2, `-50` = chậm còn 0,5. **Chỉ có hiệu lực khi `pitch` khác 0** — đây là hành vi của upstream (BytePlus); gửi riêng `speechRate` vẫn được chấp nhận (`202`) nhưng không có tác dụng. | | `loudnessRate` | integer | Không | `-50` đến `100`, mặc định `0` | Âm lượng. `0` = bình thường, `100` = to gấp 2, `-50` = nhỏ còn 0,5. | | `pitch` | integer | Không | `-12` đến `12`, mặc định `0` | Dịch cao độ theo nửa cung. Phải khác 0 để `speechRate` có hiệu lực. | | `silenceDuration` | integer | Không | `0`–`30000`, mặc định `0` | Khoảng lặng tính bằng ms được thêm vào cuối âm thanh. Chỉ áp dụng cho câu cuối cùng — hữu ích để chèn khoảng đệm trước khi nối nhiều đoạn âm thanh. | | `enableLanguageDetector` | boolean | Không | mặc định `false` | Tự động nhận diện ngôn ngữ trong văn bản đa ngôn ngữ, tránh đọc sai các từ nước ngoài. | | `explicitLanguage` | string | Không | `zh`, `zh-cn`, `en`, `ja`, `es`, `es-mx`, `id`, `pt-br`, `ko`, `it`, `de`, `fr` | Bắt buộc dùng một ngôn ngữ đầu ra cụ thể, ghi đè tính năng tự nhận diện. | | `disableMarkdownFilter` | boolean | Không | mặc định `false` | `false` (mặc định): markdown được đọc nguyên văn (`**Hello**` → "star Hello star"). `true`: markdown được phân tích và loại bỏ (`**Hello**` → "Hello"). | | `disableEmojiFilter` | boolean | Không | mặc định `false` | `false` (mặc định): emoji bị loại bỏ trước khi tổng hợp. `true`: giữ lại emoji. | | `contextTexts` | string\[] | Không | Tối đa 1 phần tử. **Chỉ TTS 2.0** | Prompt phong cách bằng ngôn ngữ tự nhiên để định hướng giọng đọc, ví dụ `["Speak a little slower"]`. Chỉ phần tử đầu tiên được dùng; không tính phí. Bị từ chối với `400` khi `voiceType` là giọng TTS 1.0. | #### Ví dụ request ```json { "voiceType": "en_female_dacey_uranus_bigtts", "text": "Hello, welcome to our platform. We are glad to have you here.", "format": "mp3", "sampleRate": 24000, "loudnessRate": 10, "contextTexts": ["Speak warmly and at a relaxed pace"] } ``` Response — `202 Accepted`: ```json { "generationId": "gen_..." } ``` Gọi `GET /api/v1/audio/generations/:generationId` định kỳ (xem mục Poll trạng thái job) để lấy kết quả. ### Generation With Reference `POST /api/v1/audio/generation-with-reference` Tạo âm thanh từ prompt viết bằng ngôn ngữ tự nhiên, có thể dựa trên giọng nói, đoạn âm thanh hoặc hình ảnh tham chiếu. #### Các trường request | Trường | Kiểu | Bắt buộc | Ràng buộc | Mô tả | | ---------------- | --------- | -------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `model` | string | Có | Phải là `seed-audio-1.0-multilingual` | Mô hình generation-with-reference được sử dụng. | | `textPrompt` | string | Có | 1–3000 ký tự | Prompt mô tả âm thanh mong muốn, hoặc văn bản cần tổng hợp. Tham chiếu các mục âm thanh theo vị trí bằng `@Audio1`, `@Audio2`, `@Audio3`. | | `references` | object\[] | Không | Tối đa 3 phần tử | Các tài nguyên tham chiếu — xem Các mục tham chiếu bên dưới. Bỏ hẳn trường này để tạo chỉ từ văn bản. | | `format` | string | Không | `mp3`, `wav`, `ogg_opus`, `pcm` | Định dạng âm thanh đầu ra. Mặc định là `mp3`. Khác với Text-to-Speech, `wav` được hỗ trợ ở đây — endpoint này trả về một buffer duy nhất không stream, nên không có vấn đề nối header của chunk. | | `sampleRate` | integer | Không | `8000`, `16000`, `24000`, `32000`, `44100`, `48000` | Tần số lấy mẫu tính bằng Hz. | | `speechRate` | integer | Không | `-50` đến `100`, mặc định `0` | Điều chỉnh tốc độ đọc. | | `loudnessRate` | integer | Không | `-50` đến `100`, mặc định `0` | Điều chỉnh âm lượng. | | `pitchRate` | integer | Không | `-12` đến `12`, mặc định `0` | Dịch cao độ theo nửa cung. | | `enableSubtitle` | boolean | Không | mặc định `false` | Bật phụ đề theo từng từ trong response. | #### Các mục tham chiếu `references[]` nhận tối đa 3 phần tử; giới hạn này được kiểm tra ở phía client. Mỗi phần tử chỉ nên có đúng một trường. Cấu trúc này **không được kiểm tra ở phía client**, nên BytePlus sẽ từ chối phần tử sai định dạng (thiếu trường, có nhiều trường hoặc chứa tổ hợp không được hỗ trợ) thay vì API trả lỗi `400` cục bộ. | Trường | Mô tả | | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `speaker` | ID người nói — một giọng `seed-tts-2.0` từ `GET /audio/voices`, hoặc một giọng đã nhân bản. Hỗ trợ nhiều mục `speaker` (ví dụ hội thoại nhiều người nói). | | `audioUrl` | URL âm thanh từ xa. Tham chiếu theo vị trí trong `textPrompt` bằng `@Audio1`, `@Audio2`, v.v. | | `audioData` | Âm thanh mã hóa base64. Được tham chiếu theo cùng cách. | | `imageUrl` | URL hình ảnh tham chiếu (jpeg/png/webp). Theo BytePlus, tham chiếu hình ảnh không thể kết hợp với tham chiếu âm thanh. | | `imageData` | Hình ảnh tham chiếu mã hóa base64. Cùng hạn chế như `imageUrl`. | #### Ví dụ request Tạo chỉ từ văn bản: ```json { "model": "seed-audio-1.0-multilingual", "textPrompt": "A warm audiobook narrator reading: The sun was setting over the mountain ridge.", "format": "mp3" } ``` Với giọng người nói: ```json { "model": "seed-audio-1.0-multilingual", "textPrompt": "Read this cheerfully: Welcome back! We have some exciting updates for you.", "references": [{ "speaker": "en_female_dacey_uranus_bigtts" }], "format": "mp3", "sampleRate": 24000 } ``` Với âm thanh tham chiếu: ```json { "model": "seed-audio-1.0-multilingual", "textPrompt": "In the style of @Audio1, read: The journey begins at dawn.", "references": [{ "audioUrl": "https://example.com/reference-voice.mp3" }], "format": "mp3" } ``` Với phụ đề: ```json { "model": "seed-audio-1.0-multilingual", "textPrompt": "Narrate this slowly and clearly: Chapter one. A new beginning.", "enableSubtitle": true, "format": "mp3" } ``` Response — `202 Accepted`: ```json { "generationId": "gen_..." } ``` ### Ước tính chi phí Mỗi sản phẩm có endpoint ước tính riêng. Gửi đúng body dự định dùng cho endpoint tương ứng đến endpoint ước tính để xem trước chi phí. Request ước tính không trừ credit và không lưu dữ liệu. > **Lưu ý:** Chi phí trả về chỉ là ước tính. Text-to-Speech tính phí theo số ký tự, vốn đã biết trước, nên ước tính khớp với số tiền thực tế. Generation With Reference tính phí theo thời lượng đầu ra, chỉ xác định được sau khi tạo xong; ước tính dựa trên độ dài prompt nên số tiền thực tế có thể khác. #### Text-to-Speech `POST /api/v1/audio/text-to-speech/estimate` Body request giống hệt `POST /api/v1/audio/text-to-speech`. ```json { "voiceType": "en_female_dacey_uranus_bigtts", "text": "Hello, welcome to our platform. We are glad to have you here." } ``` ```json { "data": { "estimatedUserCost": 0.002, "currency": "USD" }, "success": true, "status": 200 } ``` #### Generation With Reference `POST /api/v1/audio/generation-with-reference/estimate` Body request giống hệt `POST /api/v1/audio/generation-with-reference`. ```json { "model": "seed-audio-1.0-multilingual", "textPrompt": "A warm audiobook narrator reading: The sun was setting over the mountain ridge." } ``` ```json { "data": { "estimatedUserCost": 0.015, "currency": "USD" }, "success": true, "status": 200 } ``` #### Các trường response | Trường | Kiểu | Mô tả | | ------------------- | ------ | -------------------------- | | `estimatedUserCost` | number | Chi phí ước tính bằng USD. | | `currency` | string | Luôn là `"USD"`. | Nếu mức chi phí ước tính phù hợp, hãy gửi cùng body đó đến endpoint tương ứng để tạo âm thanh. ### Poll trạng thái job `GET /api/v1/audio/generations/:generationId` Endpoint này dùng chung cho cả hai sản phẩm. Dựa vào trường `product` để phân biệt chúng. | Trường | Kiểu | Mô tả | | ------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------- | | `generationId` | string | ID generation. | | `product` | string | `text-to-speech` hoặc `generation-with-reference`. | | `status` | string | `queued`, `processing`, `succeeded` hoặc `failed`. | | `audioUrl` | string | URL tải âm thanh đã ký. Có khi `succeeded`. | | `durationSeconds` | number | Thời lượng âm thanh (có thể phát) sau xử lý, tính bằng giây. Chỉ với generation-with-reference. | | `originalDurationSeconds` | number | Thời lượng đầu ra gốc của mô hình — thời lượng được tính phí. Chỉ với generation-with-reference. | | `providerUrl` | string | URL âm thanh tạm thời của BytePlus (hiệu lực \~2 giờ). Dùng `audioUrl` cho bản được lưu trữ lâu dài. Chỉ với generation-with-reference. | | `subtitle` | object | Có khi đã yêu cầu phụ đề. Chỉ với generation-with-reference — xem bên dưới. | | `error` | string | Thông báo lỗi. Có khi `status` là `failed`. | Cấu trúc `subtitle` (chỉ có khi request đặt `enableSubtitle: true`): | Trường | Kiểu | Mô tả | | ------------------------------ | --------- | ------------------------------------------------------------------------------------------------- | | `subtitle.text` | string | Toàn bộ văn bản phiên âm. | | `subtitle.sentences[]` | object\[] | Các đoạn theo câu: `{ text, startTime, endTime, words }`, thời gian tính bằng ms từ đầu âm thanh. | | `subtitle.sentences[].words[]` | object\[] | Các đoạn theo từ: `{ text, startTime, endTime }`. | Ví dụ response (Generation With Reference, thành công, có bật phụ đề): ```json { "generationId": "gen_6a6...", "product": "generation-with-reference", "status": "succeeded", "audioUrl": "https://cdn.example.com/assets/6a6.../audio.mp3", "durationSeconds": 12.34, "originalDurationSeconds": 12.34, "subtitle": { "text": "Hello. Stay close.", "sentences": [ { "text": "Hello.", "startTime": 0, "endTime": 1800, "words": [ { "text": "Hello", "startTime": 0, "endTime": 600 }, { "text": ".", "startTime": 600, "endTime": 1800 } ] } ] } } ``` Gọi endpoint định kỳ để kiểm tra cho đến khi `status` là `succeeded` hoặc `failed`. ### Lưu ý về kiểm tra dữ liệu (validation) * `contextTexts` trong request Text-to-Speech trả về `400` khi `voiceType` được chọn là giọng TTS 1.0. * `references[]` trong request Generation With Reference: giới hạn 3 phần tử phía client (`400` nếu vượt quá); cấu trúc trường của từng phần tử (chính xác một trường, kết hợp hình ảnh/âm thanh) không được kiểm tra phía client mà sẽ bị BytePlus từ chối. * Một `speaker` không xác định (không phải giọng trong danh mục `seed-tts-2.0`) trả về `400`. * Không đủ credit trả về `403`. * Một `voiceType` không xác định trả về `400`. * Nhà cung cấp bên dưới không hỗ trợ SSML trên cả hai sản phẩm — chỉ dùng văn bản thuần. ### Khám phá mô hình và khả năng `GET /api/v1/ai/models?outputModalities=audio` lọc danh mục và chỉ trả về các mô hình âm thanh: `seed-tts-1.0`, `seed-tts-2.0` (Text-to-Speech) và `seed-audio-1.0-multilingual` (Generation With Reference). Đối tượng `capabilities.audio` cho client biết endpoint cần gọi và nơi lấy danh mục giọng đọc. Nhờ đó, bộ chọn mô hình có thể lấy thông tin từ endpoint này thay vì cố định model ID hoặc route gửi. ``` GET /api/v1/ai/models?outputModalities=audio ``` `modelId` trong danh mục là giá trị cần gửi trong trường `model` của `POST /audio/generation-with-reference`. Text-to-Speech không nhận trường `model`; mô hình được xác định ngầm bởi `voiceType` đã chọn. #### Các trường của `capabilities.audio` | Trường | Kiểu | Mô tả | | ------------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `endpoint` | string | Route gửi (tương đối với `/api/v1`) cho mô hình này: `/audio/text-to-speech` hoặc `/audio/generation-with-reference`. | | `voiceSource.endpoint` | string | Luôn là `/audio/voices` — nơi lấy danh mục giọng đọc/người nói. | | `voiceSource.resourceId` | string | `resourceId` để truyền vào `GET /audio/voices?resourceId=...` cho mô hình này. Các mô hình TTS trỏ tới phiên bản của chính chúng (`seed-tts-1.0` / `seed-tts-2.0`); Generation With Reference trỏ tới `seed-tts-2.0`, vì đó là giá trị mà trường tham chiếu `speaker` của nó chấp nhận. | | `modes` | string\[] | Các chế độ tạo được tự động chọn theo loại tham chiếu được cung cấp: `["text-only", "reference-audio", "reference-image"]`. Chỉ với Generation With Reference; không có với TTS (một chế độ ngầm định). | | `languages` | string\[] | Các mã BCP-47 mà mô hình có thể tạo. Chỉ với Generation With Reference — không có với các mô hình TTS, vì ngôn ngữ được hỗ trợ tùy theo từng giọng (xem trường `languages` của danh mục giọng đọc). | | `params` | object | Giới hạn của từng trường (giá trị enum / khoảng số), theo tên trường trong request — bản sao máy đọc được của các bảng Các trường request ở trên. | #### Ví dụ response ```json { "data": [ { "modelId": "seed-tts-2.0", "name": "Text To Speech 2.0", "providerIds": ["byteplus"], "inputModalities": ["text"], "outputModalities": ["audio"], "isActive": true, "capabilities": { "audio": { "endpoint": "/audio/text-to-speech", "voiceSource": { "endpoint": "/audio/voices", "resourceId": "seed-tts-2.0" }, "params": { "format": { "type": "enum", "values": ["mp3", "ogg_opus", "pcm"], "default": "mp3" }, "speechRate": { "type": "range", "min": -50, "max": 100, "default": 0 }, "pitch": { "type": "range", "min": -12, "max": 12, "default": 0 } } } } }, { "modelId": "seed-audio-1.0-multilingual", "name": "Dola-Seed-Audio 1.0", "providerIds": ["byteplus"], "inputModalities": ["text", "audio", "image"], "outputModalities": ["audio"], "isActive": true, "capabilities": { "audio": { "endpoint": "/audio/generation-with-reference", "voiceSource": { "endpoint": "/audio/voices", "resourceId": "seed-tts-2.0" }, "modes": ["text-only", "reference-audio", "reference-image"], "languages": [ "en", "zh", "ja", "ko", "es-MX", "id", "de", "pt-BR", "fr", "th", "vi", "ms", "fil", "it", "ru", "nl", "pl", "tr", "sv", "es" ], "params": { "format": { "type": "enum", "values": ["mp3", "wav", "ogg_opus", "pcm"], "default": "mp3" }, "sampleRate": { "type": "enum", "values": ["8000", "16000", "24000", "32000", "44100", "48000"], "default": "24000" }, "enableSubtitle": { "type": "bool", "default": false } } } } } ], "success": true, "status": 200, "timestamp": "2026-07-22T10:00:00.000Z" } ``` Xem mục Cấu trúc giá trị của `capabilities.params` để biết `type` của từng phần tử trong `params` (`enum`, `range`, `int`, `bool`, ...) xác định những trường bổ sung nào. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.avis.net/vi/tai-lieu-api/endpoints/audio-generation.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.