> For the complete documentation index, see [llms.txt](https://api-docs.vbee.vn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.vbee.vn/vbee-api/text-to-speech/realtime-api.md).

# Realtime API

**URL**: <https://api.vbee.vn/v1/tts&#x20>;

**Method**: POST

**Tham số Header**    &#x20;

| Tham số       | Giá trị          | Kiểu dữ liệu                           | Tính bắt buộc | Mô tả                                               |
| ------------- | ---------------- | -------------------------------------- | ------------- | --------------------------------------------------- |
| Authorization | Bearer {{token}} | <p></p><p></p><p>String</p><p><br></p> | Có            | Token xác thực dạng Bearer: Bearer \<access\_token> |
| App-Id        | {{app-id}}       | <p></p><p></p><p>String</p><p><br></p> | Có            | ID của ứng dụng người dùng tạo                      |
| Content Type  | application/json | String                                 | Có            | Chỉ định kiểu nội dung gửi lên                      |

**Cấu trúc body của request**

<table data-header-hidden><thead><tr><th width="139"></th><th width="102"></th><th width="147"></th><th></th></tr></thead><tbody><tr><td>Tham số</td><td>Kiểu dữ liệu</td><td>Tính bắt buộc</td><td>Mô tả</td></tr><tr><td>text</td><td><p></p><p></p><p>String</p><p><br></p></td><td>Bắt buộc</td><td><p>Văn bản đầu vào cần tổng hợp. Khoảng trắng đầu cuối sẽ được tự động loại bỏ (trim). Không được để trống. </p><p>Tối đa 300 ký tự (≤ 300).</p></td></tr><tr><td>mode</td><td><p></p><p></p><p>String</p><p><br></p></td><td>Bắt buộc</td><td><p>Chế độ chuyển văn bản. </p><p>*Giá trị bắt buộc là sync để sử dụng Realtime API</p></td></tr><tr><td>voiceCode</td><td><p></p><p></p><p>String</p><p><br></p></td><td>Bắt buộc</td><td><p>Mã giọng đọc dùng để chuyển đổi văn bản. Không được để trống.</p><p>Lưu ý: Hiện chỉ hỗ trợ giọng HN - Ngọc Huyền, SG - Tường Vy, HN - Mai Phương, SG - Lan Trinh, SG - Thảo Trinh</p></td></tr><tr><td>outputFormat</td><td><p></p><p></p><p>String</p><p><br></p></td><td><p></p><p></p><p></p><p>Không</p><p><br><br></p></td><td><p>Định dạng loại tệp audio đầu ra</p><p></p><p>*Giá trị mặc định: mp3</p><p>*Định dạng đầu ra. Hỗ trợ mp3, wav và pcm.</p></td></tr><tr><td>bitrate</td><td><p></p><p></p><p>Number</p><p><br></p></td><td><p></p><p></p><p></p><p>Không</p><p><br><br></p></td><td><p>Tốc độ bit của tệp audio (kbps)</p><p> </p><p>*Giá trị mặc định: 128</p><p>*Giá trị hợp lệ: 8, 16, 32, 64, 128</p></td></tr><tr><td>speed</td><td><p></p><p></p><p>Number</p><p><br></p></td><td>Không</td><td><p>Tốc độ đọc. </p><p></p><p>*Giá trị mặc định: 1.0</p><p>*Giá trị từ 0.25 đến 1.9.</p></td></tr><tr><td>sampleRate</td><td>Number</td><td>Không</td><td><p>Tần số lấy mẫu (Hz)</p><p><br></p><p>*Giá trị mặc định: giá trị cao nhất hỗ trợ cho giọng</p><p>*Giá trị hợp lệ: 8000, 16000, 22050, 24000, 32000, 44100, 48000.</p><p>Lưu ý: tùy vào từng giọng mà có các giá trị hỗ trợ riêng.</p></td></tr></tbody></table>

```
//REQUEST EXAMPLE: 

curl -X POST https://api.vbee.vn/v1/tts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -H "App-id: your-app-id" \
  -d '{
    "text": "Xin chào, đây là giọng nói tổng hợp từ Vbee.",
    "voiceCode": "hn_female_ngochuyen_full_48k-fhg",
    "outputFormat": "mp3",
    "bitrate": 128,
    "speed": 1.0,
    "mode": "sync"
  }' \
  --output output.mp3
```

```
//SUCCESS RESPONSE: trả về từng chunk Audio binary data (MP3/WAV/PCM)
```

```
//FAILURE RESPONSE: 
//Khi có lỗi, response trả về dạng JSON:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "text must be less than or equal to 300 characters"
  }
}
```

**Danh sách Error Codes**

<table data-header-hidden><thead><tr><th width="275"></th><th width="151"></th><th></th></tr></thead><tbody><tr><td>Code</td><td>HTTP status</td><td>Mô tả</td></tr><tr><td>UNAUTHORIZED</td><td><p></p><p></p><p>401</p><p><br></p></td><td>Token không hợp lệ, thiếu Authorization header, App-id</td></tr><tr><td><p></p><p></p><p></p><p>BAD_REQUEST</p><p><br><br></p></td><td>400</td><td><p>- Body request không hợp lệ (thiếu trường bắt buộc, text > 300 ký tự, outputFormat không hỗ trợ, ...)</p><p>- Lỗi validation (ví dụ: voiceCode không tồn tại, sampleRate không hỗ trợ, syntax không hợp lệ)</p><p>- Không đủ credit</p></td></tr><tr><td>TTS_CCR_MAX_LIMIT_REACHED</td><td>429</td><td>Vượt quá số lượng concurrent requests cho phép</td></tr><tr><td>TTS_SPEND_CREDITS_FAILED</td><td>500</td><td>Trừ credit thất bại</td></tr><tr><td>INTERNAL_SERVER_ERROR</td><td>500</td><td>Lỗi nội bộ</td></tr></tbody></table>