# Giới thiệu

Vbee API được xây dựng dưới dạng một dịch vụ HTTPS, cho phép hệ thống của bạn gửi yêu cầu (request) kèm nội dung văn bản và các tham số cấu hình, sau đó nhận lại kết quả (response) là dữ liệu âm thanh tương ứng.

Nói một cách đơn giản, đây là “cầu nối” giúp các ứng dụng và website chuyển đổi văn bản thành giọng nói một cách tự động và linh hoạt.

API được tối ưu để hoạt động ổn định với các hệ thống có lưu lượng truy cập lớn, như: website tin tức, tổng đài tự động, chatbot và trợ lý ảo.

***

#### Lợi ích khi sử dụng Vbee Text-to-Speech API

Giải pháp này mang lại nhiều giá trị thiết thực cho doanh nghiệp:

* Tạo sự khác biệt cho sản phẩm với giọng nói nhân tạo có thể tùy chỉnh về phong cách, giọng điệu và cảm xúc.
* Nâng cao trải nghiệm người dùng thông qua khả năng giao tiếp bằng giọng nói tự nhiên, dễ nghe.
* Chuyển đổi văn bản thành âm thanh nhanh chóng, hỗ trợ tốt cho nội dung tiếng Việt.
* Dễ dàng mở rộng quy mô hệ thống khi nhu cầu tăng trưởng.
* Đảm bảo hiệu suất ổn định, kể cả khi lưu lượng truy cập tăng đột biến.

***

#### Phương thức trả kết quả

Tùy theo nhu cầu sử dụng, Vbee API hỗ trợ cách nhận kết quả như sau:

* Bất đồng bộ (Asynchronous): Hệ thống sẽ xử lý yêu cầu trước, sau đó gửi kết quả về một đường dẫn (Callback URL) do bạn cung cấp.\
  → Phù hợp với nội dung dài hoặc xử lý số lượng lớn như: báo nói, sách nói, sản xuất nội dung media (YouTube, TikTok,…).
* Đồng bộ (Synchronous): Kết quả được trả về ngay trong phản hồi của API.
  \
  → Phù hợp với nội dung ngắn, cần tốc độ phản hồi nhanh như chatbot hoặc thông báo tức thời.

***

Với những ưu điểm trên, Vbee API không chỉ là một công cụ kỹ thuật mà còn là nền tảng giúp doanh nghiệp nâng cao trải nghiệm người dùng, mở rộng quy mô và thúc đẩy đổi mới trong các sản phẩm số.


# Tạo ứng dụng App ID và Token

Tạo ứng dụng API nhằm cung cấp cách thức kết nối đơn giản, an toàn và linh hoạt để chuyển đổi văn bản thành giọng nói (TTS) thông qua các yêu cầu HTTP.

1. Truy cập vào <https://studio.vbee.vn/apps>
2. Tạo ứng dụng

​(1) Chọn Tích hợp API

<figure><img src="https://3955878996-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwLDr6yraeSQhkHtTDCIy%2Fuploads%2FLSwj0dxu7m5dmnGqXMgn%2Funknown.jpeg?alt=media&amp;token=4d54a9ea-8919-4d58-b672-29def5c45ff6" alt=""><figcaption></figcaption></figure>

(2) Chọn "Tạo ứng dụng"

<figure><img src="https://3955878996-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwLDr6yraeSQhkHtTDCIy%2Fuploads%2F1vKqUrS4WuCZbTrXbx7j%2Funknown.jpeg?alt=media&amp;token=0de11164-d118-4a0b-afa5-f9531be70d74" alt=""><figcaption></figcaption></figure>

(3) Nhập ​Tên ứng dụng

<figure><img src="https://3955878996-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwLDr6yraeSQhkHtTDCIy%2Fuploads%2FoWz2IrEmd96yWOkUCyJb%2Funknown.png?alt=media&amp;token=72630b9b-3e77-4006-9993-2cdf06ac1b43" alt=""><figcaption></figcaption></figure>

(4) Chọn Hạn dùng

* Chọn hạn dùng theo thời gian cố định

<figure><img src="https://3955878996-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwLDr6yraeSQhkHtTDCIy%2Fuploads%2FjI5bmFeiPmNTJ1PzfrlW%2FUntitled1.png?alt=media&amp;token=389af8c7-5d55-48e1-b260-50d4f9c29100" alt=""><figcaption></figcaption></figure>

Người dùng chọn hạn dùng theo thời gian cố định: 7 ngày, 30 ngày, 60 ngày, 90 ngày

Hệ thống tự động hiển thị Ngày hết hạn của token tương ứng.

Khi hết hạn thì token bị vô hiệu hóa, người dùng tạo ứng dụng mới để tiếp tục sử dụng.

* Chọn Hạn dùng Vĩnh viễn

<figure><img src="https://3955878996-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwLDr6yraeSQhkHtTDCIy%2Fuploads%2Fa91ojHgOijSNCMQ96Hre%2FUntitled1.png?alt=media&amp;token=79b71273-bd83-4686-9a10-95980e0a142d" alt=""><figcaption></figcaption></figure>

Người dùng chọn hạn dùng Vĩnh viễn

Không có ngày hết hạn.

* Chọn Hạn dùng Tùy chỉnh

<figure><img src="https://3955878996-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwLDr6yraeSQhkHtTDCIy%2Fuploads%2FWjOurlKMN4RfN9zPHpfv%2FUntitled1.png?alt=media&amp;token=1453138f-82cb-4007-97e8-755c6a552840" alt=""><figcaption></figcaption></figure>

Người dùng chọn Hạn dùng là Tùy chỉnh

Hệ thống hiển thị Ngày hết hạn mặc định là Ngày hiện tại.

Người dùng có thể thay đổi Ngày hết hạn tùy theo nhu cầu sử dụng ứng dụng của cá nhân.

(5) Nhấn nút "Tạo" để tạo mới ứng dụng

<figure><img src="https://3955878996-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwLDr6yraeSQhkHtTDCIy%2Fuploads%2F6sigMMG7MmeRn8kGw5ZK%2Funknown.png?alt=media&amp;token=0d7d617d-3da3-42e7-8c3a-1f745f2ea09f" alt=""><figcaption></figcaption></figure>

3\. Tìm kiếm danh sách ứng dụng​

<figure><img src="https://3955878996-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwLDr6yraeSQhkHtTDCIy%2Fuploads%2FJydU85Aasue8nRgJ2Wj7%2FUntitled1.png?alt=media&amp;token=bd365f72-bf70-41b2-86fc-b0604115fa66" alt=""><figcaption></figcaption></figure>

Người dùng nhập từ khóa vào ô tìm kiếm&#x20;

Hệ thống hiển thị danh sách ứng dụng có Tên ứng dụng phù hợp với từ khóa tương ứng.​

4\. Xem thông tin chi tiết ứng dụng

​(1) Chọn và nhấn vào ứng dụng cần xem thông tin

<figure><img src="https://3955878996-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwLDr6yraeSQhkHtTDCIy%2Fuploads%2FxzVeE2Gtv1PFw6eUpUBu%2Funknown.jpeg?alt=media&amp;token=73ca0938-df37-4d16-9fc1-18ac67767a96" alt=""><figcaption></figcaption></figure>

(2) Xem thông tin chi tiết ứng dụng

<figure><img src="https://3955878996-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwLDr6yraeSQhkHtTDCIy%2Fuploads%2FJEZk9GFjKuG5And3OeVs%2Funknown.jpeg?alt=media&amp;token=31f262df-16bc-4165-a32c-602696ae4e26" alt=""><figcaption></figcaption></figure>

(3) Xem Báo cáo tổng quan

Người dùng chọn khoảng thời gian cần xem danh sách các yêu cầu (request) chuyển đổi theo các trạng thái tương ứng.

<figure><img src="https://3955878996-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwLDr6yraeSQhkHtTDCIy%2Fuploads%2FSri70tF2VenhKXioSP0o%2FUntitled1.png?alt=media&amp;token=cd34f661-c164-4b13-8dfc-783fbe80dfb5" alt=""><figcaption></figcaption></figure>

Có 3 trạng thái của yêu cầu:

![](https://3955878996-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwLDr6yraeSQhkHtTDCIy%2Fuploads%2F3O7Nho0YtEeGaIrLuqcd%2Funknown.png?alt=media\&token=046eead0-17fc-4352-b337-a935128d2c61)

* Đang xử lý: yêu cầu chuyển đổi đang được xử lý
* Thành công: yêu cầu chuyển đổi đã xử lý thành công
* Thất bại: yêu cầu chuyển đổi xử lý thất bại.


# Text to Speech


# Batch API

API hỗ trợ chế độ xử lý bất đồng bộ cho các tệp văn bản dài hoặc tác vụ cần thời gian xử lý lớn.

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

**Method**: POST

**Tham số Header**

<table data-header-hidden><thead><tr><th width="133"></th><th></th><th></th><th></th><th></th></tr></thead><tbody><tr><td>Tham số</td><td>Giá trị</td><td>Kiểu dữ liệu</td><td>Tính bắt buộc</td><td>Mô tả</td></tr><tr><td>Authorization</td><td>Bearer {{token}}</td><td><p></p><p></p><p>String</p><p><br></p></td><td>Có</td><td>Token xác thực dạng Bearer: Bearer &#x3C;access_token></td></tr><tr><td>App-Id</td><td>{{app-id}}</td><td><p></p><p></p><p>String</p><p><br></p></td><td>Có</td><td>ID của ứng dụng người dùng tạo</td></tr><tr><td>Content-Type</td><td>application/json</td><td>String</td><td>Có</td><td>Chỉ định kiểu nội dung JSON</td></tr></tbody></table>

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

<table data-header-hidden><thead><tr><th width="132"></th><th width="123"></th><th width="142"></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>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ỏ. Không được để trống. </p><p>Tối đa 100.000 ký tự</p></td></tr><tr><td>mode</td><td><p></p><p></p><p>String</p><p><br></p></td><td>Có</td><td><p>Chế độ chuyển văn bản. </p><p>*Giá trị bắt buộc là async để sử dụng Batch API.</p></td></tr><tr><td>webhookUrl</td><td>String</td><td>Có</td><td>Webhook để nhận kết quả của request</td></tr><tr><td>voiceCode</td><td><p></p><p></p><p>String</p><p><br></p></td><td>Có</td><td>Mã giọng đọc dùng để chuyển đổi văn bản.</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><br></p><p>*Giá trị mặc định: mp3</p><p>*Định dạng đầu ra. Hỗ trợ mp3 và wav.</p><p><br></p><p>Lưu ý: hiện tại chỉ hỗ trợ mp3 và wav, nếu truyền pcm lên thì sẽ tổng hợp văn bản lỗi..</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><br></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><br></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ị mặc định riêng.</p></td></tr><tr><td>emphasisIntensity</td><td>Number</td><td><p></p><p></p><p></p><p>Không</p><p><br><br></p></td><td><p>Mức độ nhấn nhá. </p><p><br></p><p>*Giá trị số nguyên từ 0 đến 100, phải là bội số của 10. </p><p>*Chỉ áp dụng cho một số giọng có hỗ trợ tính năng nhấn nhá.</p></td></tr><tr><td>clientPause</td><td>Object</td><td><p></p><p></p><p></p><p>Không</p><p><br><br></p></td><td>Cấu hình thời gian ngắt nghỉ (xem bảng bên dưới).</td></tr></tbody></table>

**Cấu trúc clientPause**

<table data-header-hidden><thead><tr><th width="148"></th><th width="137"></th><th width="158"></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>majorBreak</td><td>Number</td><td>Không</td><td><p>Thời gian ngắt nghỉ dấu chấm phẩy (giây). </p><p><br></p><p>*Giá trị mặc định: 0.3</p><p>*Giá trị từ 0.1 đến 10.</p></td></tr><tr><td>mediumBreak</td><td>Number</td><td>Không</td><td><p>Thời gian ngắt nghỉ dấu phẩy (giây). </p><p><br></p><p>*Giá trị mặc định: 0.25</p><p>*Giá trị từ 0.1 đến 10.</p></td></tr><tr><td>paragraphBreak</td><td>Number</td><td>Không</td><td><p>Thời gian ngắt nghỉ xuống dòng (giây). </p><p><br></p><p>*Giá trị mặc định: 0.6</p><p>*Giá trị từ 0 đến 10.</p></td></tr><tr><td>sentenceBreak</td><td>Number</td><td>Không</td><td><p>Thời gian ngắt nghỉ dấu chấm câu (giây). </p><p><br></p><p>*Giá trị mặc định: 0.45</p><p>*Giá trị từ 0.1 đến 10.</p></td></tr></tbody></table>

**Chú ý:**

\
**Các audio link trả về chỉ có thời hạn trong vòng 3 phút, sau 3 phút audio link sẽ hết hạn và không thể sử dụng. Audio vẫn sẽ được lưu trữ trên hệ thống trong vòng 3 ngày kể từ thời điểm chuyển văn bản thành công. Muốn lấy link mới, bạn gọi api Get Request (bên dưới) để lấy lại audio link mới.**

**Kết quả trả về:**&#x20;

* requestId: ID của request, dùng để tracking
* status: Trạng thái của request
* error\_code: mã lỗi
* error\_message: Mô tả chi tiết lỗi

<pre><code><strong>//REQUEST EXAMPLE: 
</strong>curl -X POST https://api.vbee.vn/v1/tts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer &#x3C;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",
    "mode": "async",
    "outputFormat": "mp3",
    "bitrate": 128,
    "speed": 1.0,
    "webhookUrl": "https://your-domain.com/callback"
  }'
</code></pre>

```
//SUCCESS RESPONSE: 
{
  "requestId": "eb75e2b0-ce65-4e85-8450-2d09728d996b",
  "status": "PROCESSING"
}
```

```
//FAILURE RESPONSE: 
//Khi có lỗi, response trả về dạng JSON:
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "webhookUrl must be defined at path webhookUrl"
  }
}
```

**Danh sách Error Codes**

<table data-header-hidden><thead><tr><th width="264"></th><th width="126"></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, hoặc thiếu appId (trong body hoặc 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ệ. Ví dụ: thiếu trường bắt buộc, sampleRate không hợp lệ</p><p>- Lỗi cấu hình request không hợp lệ (ví dụ: voiceCode không tồn tại)</p></td></tr><tr><td>INTERNAL_SERVER_ERROR</td><td>500</td><td>Lỗi nội bộ</td></tr></tbody></table>


# Callback API

Callback API chỉ áp dụng với Batch API

Khi request thành công, hệ thống VBEE TTS sẽ gửi đến Callback URL một HTTP POST như sau

**URL**: callback url truyền lên khi gọi API Create speech

**Method**: POST

**Body**:

<table data-header-hidden><thead><tr><th width="177"></th><th width="165"></th><th></th></tr></thead><tbody><tr><td>Thuộc tính</td><td>Kiểu dữ liệu</td><td>Mô tả</td></tr><tr><td>app_id</td><td>String</td><td>ID của ứng dụng</td></tr><tr><td>request_id</td><td>String</td><td>ID của request</td></tr><tr><td>characters</td><td>Number</td><td>Số ký tự của đoạn văn bản</td></tr><tr><td>voice_code</td><td>String</td><td>Mã giọng</td></tr><tr><td>audio_type</td><td>String</td><td>Định dạng tệp audio đầu ra</td></tr><tr><td>speed_rate</td><td>Number</td><td>Tốc độ đọc</td></tr><tr><td>sample_rate</td><td>String</td><td>Sample rate của audio đầu ra</td></tr><tr><td>bitrate</td><td>Number</td><td>Bitrate của tệp audio đầu ra</td></tr><tr><td>created_at</td><td>String</td><td>Thời gian khởi tạo request</td></tr><tr><td>status</td><td>String</td><td><p>Trạng thái của request</p><p>* SUCCESS: Thành công</p><p>* FAILURE: Thất bại</p></td></tr><tr><td>audio_link</td><td>String</td><td>Đường dẫn tải tệp audio tổng hợp</td></tr></tbody></table>

```
//Example request
{
    "app_id": "{{app_id}}",
    "response_type": "indirect",
    "callback_url": "https://mydomain/callback",
    "input_text": "Xin Chào mừng đén với website của chúng tôi! Đây là trang web cung cấp một giải pháp văn bản thành giọng nói, trên cơ sở, nó hỗ trợ các doanh nghiệp xây dựng các hệ thống trung tâm cuộc gọi tự động, hệ thống thông báo công khai, trợ lý ảo, tin tức âm thanh, podcast, sách âm thanh và tường thuật phim.",
    "voice_code": "hn_female_ngochuyen_full_48k-fhg",
    "audio_type":"mp3",
    "bitrate": 128,
    "speed_rate": "1.0"
}

```


# Get request

Lấy thông tin của request bằng cách gọi API

**URL**: <https://api.vbee.vn/v1/tts/requests/\\{{requestId\\}}&#x20>;

**Method**: GET

**Tham số Header**

<table data-header-hidden><thead><tr><th width="131"></th><th></th><th></th><th></th><th></th></tr></thead><tbody><tr><td>Tham số</td><td>Giá trị</td><td>Kiểu dữ liệu</td><td>Tính bắt buộc</td><td>Mô tả</td></tr><tr><td>Authorization</td><td>Bearer {{token}}</td><td><p></p><p></p><p>String</p><p><br></p></td><td>Có</td><td>Token xác thực dạng Bearer: Bearer &#x3C;access_token></td></tr><tr><td>App-Id</td><td>{{app-id}}</td><td><p></p><p></p><p>String</p><p><br></p></td><td>Có</td><td>ID của ứng dụng người dùng tạo</td></tr><tr><td>Content-Type</td><td>application/json</td><td><br></td><td>Có</td><td>Chỉ định kiểu nội dung JSON</td></tr></tbody></table>

**Tham số Path**

<table data-header-hidden><thead><tr><th width="110"></th><th width="140"></th><th></th><th></th><th></th></tr></thead><tbody><tr><td>Tham số</td><td>Giá trị</td><td>Kiểu dữ liệu</td><td>Tính bắt buộc</td><td>Mô tả</td></tr><tr><td>requestId</td><td>{{requestId}}</td><td><p></p><p></p><p>String</p><p><br></p></td><td>Có</td><td><p></p><p>ID của TTS request cần lấy chi tiết</p><p></p></td></tr></tbody></table>

**Kết quả trả về:**&#x20;

* requestId: ID của request, dùng để tracking
* status: Trạng thái của request
* error\_code: mã lỗi
* error\_message: Mô tả chi tiết lỗi

```
//REQUEST EXAMPLE: 

curl -X GET "https://api.vbee.vn/v1/tts/requests/eb75e2b0-ce65-4e85-8450-2d09728d996b" \
  -H "Authorization: Bearer <access_token>" \
  -H "App-Id: your-app-id"
```

```
//SUCCESSFUL RESPONSE: (status = COMPLETED)

{
  "requestId": "eb75e2b0-ce65-4e85-8450-2d09728d996b",
  "status": "COMPLETED",
  "audioLink": "https://example.com/audio/eb75e2b0.mp3"
}
```

```
//RESPONSE PROCESSING  (status = PROCESSING)

{
  "requestId": "eb75e2b0-ce65-4e85-8450-2d09728d996b",
  "status": "PROCESSING"
}
```

```
//FAILURE RESPONSE (status = `FAILED`)

{
    "error": {
        "code": "BAD_REQUEST",
        "message": "Request is not found"
    }
}
```

**Danh sách Error Codes**

| Code                    | HTTP status                         | Mô tả                                                                                                                                                                |
| ----------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| UNAUTHORIZED            | <p></p><p></p><p>401</p><p><br></p> | Token không hợp lệ, thiếu Authorization header, hoặc thiếu appId (trong body hoặc header app-id)                                                                     |
| BAD\_REQUEST            | 400                                 | <p>- Body request không hợp lệ. Ví dụ: thiếu trường bắt buộc, sampleRate không hợp lệ</p><p>- Lỗi cấu hình request không hợp lệ (ví dụ: voiceCode không tồn tại)</p> |
| INTERNAL\_SERVER\_ERROR | 500                                 | Lỗi nội bộ                                                                                                                                                           |


# Realtime API

API với chế độ sync phù hợp với các tệp văn bản ngắn, cho phép audio được trả về theo từng chunk liên tục ngay khi xử lý, giúp phát âm thanh gần như. Thời gian phản hồi trung bình \~ 500ms, tối đa 1s.

**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>


# Speech to Text


# Batch API

API hỗ trợ chế độ xử lý bất đồng bộ cho các tệp audio dài hoặc tác vụ cần thời gian xử lý lớn.

**URL**: <https://api.vbee.vn/v1/stt>

**Method**: POST

**Tham số Header**

| **Tham số**   | **Giá trị**         | **Tính bắt buộc** | **Mô tả**                                                                                                  |
| ------------- | ------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------- |
| Authorization | Bearer {{token}}    | Có                | Token đại diện cho App gọi API, được sinh ra dưới dạng JWT có thời hạn do lúc khởi tạo App người dùng chọn |
| App-Id        | {{app-id}}          | Có                | <p><br></p>                                                                                                |
| Content Type  | multipart/form-data | Có                |                                                                                                            |

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

| **Tham số**  | **Kiểu dữ liệu** | **Tính bắt buộc** | **Mô tả**                                                                                                     |
| ------------ | ---------------- | ----------------- | ------------------------------------------------------------------------------------------------------------- |
| audioContent | File             | Có                | <p>Tệp WAV — xem bảng giới hạn bên dưới<br>Sample rate được chấp nhận: 8000,16000,22050,32000,44100,48000</p> |
| audioUrl     | String           | Không             | URL HTTP(S) trỏ đến tệp WAV — cùng giới hạn                                                                   |
| mode         | String           | Có                | Giá trị bắt buộc: async                                                                                       |
| webhookUrl   | String           | Không             | URL để server POST kết quả khi job async hoàn tất.                                                            |

Giới hạn tệp như sau:

| <p><br></p>    | **Giới hạn**            | **Điều kiện lỗi**     |
| -------------- | ----------------------- | --------------------- |
| Kích thước tệp | Kích thước tệp < 100 MB | 400 nếu size ≥ 100 MB |

**Kết quả trả về**

* **transcriptId**: ID transcript
* **status**: trạng thái của API
  * PENDING: đang chờ xử lý
  * PROCESSING: đang nhận dạng
  * COMPLETED: xong
  * FAILED: thất bại
* **transcript**: Văn bản nhận dạng ghép từ tất cả các utterances
* **utterances**: Danh sách từng đoạn nhận dạng gồm text, startTime, endTime (giây)
* **audioDurationSeconds**: Thời lượng WAV (giây, làm tròn lên) dùng để tính prepaid billing

```
// Request
curl -X POST https://<host>/v1/stt \
  -H "Authorization: Bearer <token>" \
  -H "App-ID: <app-id>" \
  -F "audioContent=@long-recording.wav" \
  -F "mode=async" \
  -F "webhookUrl=https://your-server.com/webhook/stt"

```

```
// Response
{
  "transcriptId": "job-uuid-456",
  "status": "COMPLETED",
  "transcript": "nội dung toàn bộ file audio",
  "utterances": [
    {
      "text": "câu đầu tiên",
      "startTime": 0.1,
      "endTime": 3.8
    },
    {
      "text": "câu thứ hai",
      "startTime": 4.2,
      "endTime": 7.5
    }
  ],
  "audioDurationSeconds": 8
}

```


# Get transcript

Lấy lại (truy xuất) một transcript đã được tạo trước đó bằng transcriptId

**URL**: <https://api.vbee.vn/v1/stt/transcripts/:transcriptId>

**Method**: GET

**Tham số Header**

| **Tham số**   | **Giá trị**      | **Tính bắt buộc** | **Mô tả**                                                                                                  |
| ------------- | ---------------- | ----------------- | ---------------------------------------------------------------------------------------------------------- |
| Authorization | Bearer {{token}} | Có                | Token đại diện cho App gọi API, được sinh ra dưới dạng JWT có thời hạn do lúc khởi tạo App người dùng chọn |
| App-Id        | {{app-id}}       | Có                | <p><br></p>                                                                                                |

**Kết quả trả về**

* **transcriptId**: ID transcript
* **status**: trạng thái của API
  * PENDING: đang chờ xử lý
  * PROCESSING: đang nhận dạng
  * COMPLETED: xong
  * FAILED: thất bại
* **transcript**: Văn bản nhận dạng ghép từ tất cả các utterances
* **utterances**: Danh sách từng đoạn nhận dạng gồm text, startTime, endTime (giây)
* **audioDurationSeconds**: Thời lượng WAV (giây, làm tròn lên) dùng để tính prepaid billing

***Khuyến nghị polling interval***: 2–5 giây.

```
curl https://api.vbee.vn/api/v1/stt/transcripts/job-uuid-456 \
  -H "Authorization: Bearer <token>" \
  -H "App-ID: <app-id>"
```

```
// Response khi COMPLETE
{
  "transcriptId": "job-uuid-456",
  "status": "COMPLETED",
  "transcript": "nội dung toàn bộ file audio",
  "utterances": [
    {
      "text": "câu đầu tiên",
      "startTime": 0.1,
      "endTime": 3.8
    },
    {
      "text": "câu thứ hai",
      "startTime": 4.2,
      "endTime": 7.5
    }
  ],
  "audioDurationSeconds": 8
}
```


# Realtime API

API với chế độ sync phù hợp với các tệp audio ngắn, cho phép xử lý và trả kết quả ngay trong response mà không cần polling. Thời gian phản hồi trung bình \~ 500ms, tối đa 1s.

**URL**: <https://api.vbee.vn/v1/stt>

**Method**: POST

**Tham số Header**

| **Tham số**   | **Giá trị**         | **Tính bắt buộc** | **Mô tả**                                                                                                  |
| ------------- | ------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------- |
| Authorization | Bearer {{token}}    | Có                | Token đại diện cho App gọi API, được sinh ra dưới dạng JWT có thời hạn do lúc khởi tạo App người dùng chọn |
| App-Id        | {{app-id}}          | Có                | <p><br></p>                                                                                                |
| Content Type  | multipart/form-data | Có                |                                                                                                            |

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

| **Tham số**  | **Kiểu dữ liệu** | **Tính bắt buộc** | **Mô tả**                                                                                                     |
| ------------ | ---------------- | ----------------- | ------------------------------------------------------------------------------------------------------------- |
| audioContent | File             | Có                | <p>Tệp WAV — xem bảng giới hạn bên dưới<br>Sample rate được chấp nhận: 8000,16000,22050,32000,44100,48000</p> |
| audioUrl     | String           | Không             | URL HTTP(S) trỏ đến tệp WAV — cùng giới hạn                                                                   |
| mode         | String           | Có                | Sync mode: Phù hợp cho tệp audio ngắn (Realtime STT)                                                          |
| webhookUrl   | String           | Không             | URL để server POST kết quả khi job sync hoàn tất.                                                             |

Giới hạn tệp như sau:

| <p><br></p>    | **Giới hạn**               | **Điều kiện lỗi**      |
| -------------- | -------------------------- | ---------------------- |
| Thời lượng     | Thời lượng audio < 10 giây | 400 nếu duration ≥ 10s |
| Kích thước tệp | Kích thước tệp < 10 MB     | 400 nếu size ≥ 10MB    |

Kết quả trả về

* **Response Type**: text/json
* **transcriptId**: ID transcript, dùng để poll kết quả
* **status**: trạng thái của API
  * PENDING: đang chờ xử lý
  * PROCESSING: đang nhận dạng
  * COMPLETED: xong
  * FAILED: thất bại
* **transcript**: Văn bản nhận dạng ghép từ tất cả các utterances
* **utterances**: Danh sách từng đoạn nhận dạng gồm text, startTime, endTime (giây)
* **audioDurationSeconds**: Thời lượng WAV (giây, làm tròn lên) dùng để tính prepaid billing

```
// Example Request
curl -X POST https://<host>/v1/stt \
  -H "Authorization: Bearer <token>" \
  -H "App-ID: <app-id>" \
  -F "audioContent=@recording.wav" \
  -F "mode=sync"

```

```
// Example Response
{
  "transcriptId": "job-uuid-123",
  "status": "COMPLETED",
  "transcript": "xin chào thế giới",
  "utterances": [
    {
      "text": "xin chào thế giới",
      "startTime": 0,
      "endTime": 3.2
    }
  ],
  "audioDurationSeconds": 4
}

```


# Callback API

Callback API áp dụng với Batch API và Realtime API (optional)

Khi request thành công, hệ thống sẽ gửi đến webhookURL một POST như sau

**URL**: callback url truyền lên khi gọi API create text

**Method**: POST

| **Tham số**   | **Kiểu dữ liệu** | **Mô tả**                                                         |
| ------------- | ---------------- | ----------------------------------------------------------------- |
| transcriptId  | String           | ID transcript                                                     |
| status        | String           | Trạng thái của API                                                |
| transcript    | String           | Văn bản nhận dạng ghép từ tất cả các utterances                   |
| utterances    | String           | Danh sách từng đoạn nhận dạng gồm text, startTime, endTime (giây) |
| audioDuration | String           | Thời lượng WAV                                                    |
| errorMessage  | String           | Mã lỗi khi status = FAILED                                        |

```
// Payload webhook (POST về webhookUrl):

{
  "transcriptId": "job-uuid-456",
  "status": "COMPLETED",
  "transcript": "nội dung nhận dạng",
  "utterances": [...],
  "audioDuration": 8
}

// Khi status = FAILED

{
  "transcriptId": "job-uuid-456",
  "status": "FAILED",
  "errorMessage": "Provider reported failure",
  "audioDuration": 8
}
```


# Streaming API

Streaming API cho phép client gửi audio liên tục theo thời gian thực (realtime) qua WebSocket và nhận kết quả nhận dạng ngay lập tức (thời gian phản hồi trung bình \~ 500ms, tối đa 1s)

### Tóm tắt luồng hoạt động

1. Kết nối WebSocket
2. Gửi cấu hình khởi tạo
3. Xác nhận từ hệ thống
4. Gửi dữ liệu âm thanh liên tục
5. Nhận kết quả theo thời gian thực
6. Thông báo khi hoàn tất gửi audio
7. Nhận kết quả cuối và kết thúc

### **Bước 1: Kết nối WebSocket**

Client tạo kết nối WebSocket với API:

wss\://api.vbee.vn/v1/stt/realtime?token=\<token>\&appId=\<app-id>

Nếu token không hợp lệ → kết nối sẽ bị đóng ngay.

Nếu hợp lệ: Server xác thực token (tự động)

### **Bước 2: Gửi cấu hình khởi tạo (STREAMING\_CONFIG)**

Sau khi kết nối thành công, client bắt buộc gửi 1 message cấu hình bao gồm các tham số:

```
{
  "type": "STREAMING_CONFIG",
  "config": {
    "sampleRateHertz": 8000,
    "sampleSizeByte": 2,
    "channel": 1,
    "interimResults": true,
    "vadConfig": {
      "noInputTimeoutMs": 10000,
      "speechCompleteTimeoutMs": 800
    },
    "sessionId": "my-optional-session-id"
  }
}
```

| **Tham số**                       | **Kiểu dữ liệu** | **Tính bắt buộc** | **Mô tả**                                                               |
| --------------------------------- | ---------------- | ----------------- | ----------------------------------------------------------------------- |
| sampleRateHertz                   | integer          | Có                | Tần số lấy mẫu (8000 hoặc 16000 Hz)                                     |
| sampleSizeByte                    | integer          | Có                | Số byte mỗi sample (luôn = 2)                                           |
| channel                           | integer          | Có                | Số kênh (chỉ hỗ trợ 1 – mono)                                           |
| interimResults                    | boolean          | Không             | <p>Nhận kết quả tạm thời khi đang nói</p><p>Giá trị mặc định: false</p> |
| sessionId                         | string           | Không             | Session ID tự đặt để tracking/debug                                     |
| vadConfig.noInputTimeoutMs        | integer          | <p>Không<br></p>  | Timeout (ms) nếu không phát hiện âm thanh. Range: `3000–10000`          |
| vadConfig.speechCompleteTimeoutMs | integer          | Không             | Thời gian im lặng (ms) để xác định hết câu. Range: `500–3000`           |

Sau khi gửi config, cần chờ server trả về READY rồi mới gửi audio.

### **Bước 3: Xác nhận từ hệ thống (READY)**

Server trả về sau khi sẵn sàng nhận audio:

```
{
  "type": "READY",
  "sessionId": "srv-session-abc123"
}
```

### **Bước 4: Gửi dữ liệu âm thanh liên tục (**&#x41;UDIO\_CHUN&#x4B;**)**

Client gửi audio liên tục dưới dạng chunk:

```
{
  "type": "AUDIO_CHUNK",
  "audioContent": "<base64-encoded-raw-pcm>"
}
```

Yêu cầu audio:

| Thuộc tính  | Giá trị bắt buộc                                      |
| ----------- | ----------------------------------------------------- |
| Encoding    | Raw PCM (Linear PCM, không có WAV header)             |
| Bit depth   | 16-bit signed integer, little-endian                  |
| Channels    | Mono (1 channel)                                      |
| Sample rate | Phải khớp với sampleRateHertz trong STREAMING\_CONFIG |

Chunk size khuyến nghị:

| Sample Rate | Chunk Size | Thời lượng                 |
| ----------- | ---------- | -------------------------- |
| 8000 Hz     | 1280 bytes | 80ms — 1280 / (8000 × 2)   |
| 16000 Hz    | 3200 bytes | 100ms — 3200 / (16000 × 2) |

Gửi chunk đều đặn theo thời gian thực (80–100ms/chunk). Chunk không đều làm giảm chất lượng nhận dạng.

### **Bước 5: Nhận kết quả theo thời gian thực**

**5.1. Kết quả tạm thời (INTERIM\_RESULT)**

Kết quả trả về trong lúc người dùng đang nói, có thể thay đổi liên tục và không phải kết quả cuối cùng. Chỉ nhận được khi `interimResults: true`.

```
{
  "type": "INTERIM_RESULT",
  "text": "gần đó momo á",
  "isFinal": false,
  "stability": 0.8,
  "startTime": 11.36,
  "endTime": 12.96,
  "startVoiceTime": 11.68,
  "endVoiceTime": 12.64
}
```

Các kết quả nhận được như sau:

| **Tham số**    | **Kiểu dữ liệu** | **Mô tả**                                         |
| -------------- | ---------------- | ------------------------------------------------- |
| text           | string           | Văn bản tạm thời, sẽ thay đổi ở interim tiếp theo |
| isFinal        | boolean          | Luôn là false                                     |
| stability      | float            | Mức độ ổn định 0.0–1.0. Cao = ít thay đổi hơn     |
| startTime      | float            | Thời điểm bắt đầu utterance (giây) trong stream   |
| endTime        | float            | Thời điểm kết thúc tạm thời (giây) — tăng dần     |
| startVoiceTime | float            | Thời điểm phát hiện giọng nói bắt đầu             |
| endVoiceTime   | float            | Thời điểm phát hiện giọng nói kết thúc tạm thời   |

**5.2. Kết quả chính thức (FINAL\_RESULT)**

Kết quả trả về khi kết thúc một câu, là kết quả cuối cùng và không thay đổi.

```
{
  "type": "FINAL_RESULT",
  "text": "anh thanh toán momo á",
  "textRaw": " anh thanh toán momo á",
  "isFinal": true,
  "confidenceScore": 0.92,
  "startTime": 11.36,
  "endTime": 13.44,
  "startVoiceTime": 11.68,
  "endVoiceTime": 12.64,
  "speechType": "detected-speech",
  "status": "SUCCESS"
}
```

Các kết quả nhận được như sau:

| **Tham số**     | **Kiểu dữ liệu** | **Mô tả**                                                                              |
| --------------- | ---------------- | -------------------------------------------------------------------------------------- |
| text            | string           | Văn bản chính thức, đã qua hậu xử lý                                                   |
| textRaw         | string           | Văn bản thô chưa xử lý                                                                 |
| isFinal         | boolean          | Luôn là true                                                                           |
| confidenceScore | float            | Độ tin cậy 0.0 – 1.0                                                                   |
| startTime       | float            | Thời điểm bắt đầu utterance (giây)                                                     |
| endTime         | float            | Thời điểm kết thúc tạm thời (giây)                                                     |
| speechType      | string           | <ul><li>detected-speech: có tiếng nói </li><li>no-speech: không có tiếng nói</li></ul> |
| status          | string           | SUCCESS hoặc FAILURE                                                                   |

### **Bước 6: Thông báo khi hoàn tất gửi audio (DONE)**

Gửi sau khi truyền hết toàn bộ audio

```
{
  "type": "DONE"
}
```

PING (Keep-alive)\
Gửi định kỳ mỗi 20–30 giây khi không có audio để duy trì kết nối.

```
{ "type": "PING" }
```

Server trả cho mỗi lần PING

```
{ "type": "PONG" }
```

### **Bước 7: Nhận kết quả cuối và kết thúc (**&#x53;TREAM\_EN&#x44;**)**&#x20;

Gửi sau khi server xử lý xong Done signal và đã gửi FinalResult cuối. Server sẽ đóng kết nối sau message này.

```
{
  "type": "STREAM_END",
  "sessionId": "srv-session-abc123",
  "totalUtterances": 4
}
```

Các kết quả nhận được như sau:

| Tham số         | Kiểu dữ liệu | Mô tả                                        |
| --------------- | ------------ | -------------------------------------------- |
| sessionId       | string       | Session ID của session vừa kết thúc          |
| totalUtterances | string       | Tổng số utterance đã nhận dạng trong session |

Khi session vượt quá 90 giây sẽ nhận được:

* type: ERROR
* code: SESSION\_TIMEOUT
* message: Session exceeded maximum duration

**Danh sách mã lỗi:**

<table data-header-hidden><thead><tr><th></th><th width="165"></th><th width="96"></th><th></th></tr></thead><tbody><tr><td><strong>code</strong></td><td><strong>Giai đoạn</strong></td><td><strong>retryable</strong></td><td><strong>Mô tả</strong></td></tr><tr><td>UNAUTHORIZED</td><td>AUTHENTICATING</td><td>false</td><td>Token không hợp lệ hoặc hết hạn</td></tr><tr><td>STT_INSUFFICIENT_SECONDS</td><td>AUTHENTICATING</td><td>false</td><td>Không đủ số giây trong tài khoản</td></tr><tr><td>STT_MAX_CCR_REACHED</td><td>AUTHENTICATING</td><td>true</td><td>Đã đạt giới hạn concurrent session</td></tr><tr><td>STT_INVALID_SAMPLE_RATE</td><td>CONFIGURING</td><td>false</td><td>sampleRateHertz không phải 8000 hoặc 16000</td></tr><tr><td>STT_INVALID_CHANNEL</td><td>CONFIGURING</td><td>false</td><td>channel không phải 1</td></tr><tr><td>STT_INVALID_SAMPLE_SIZE</td><td>CONFIGURING</td><td>false</td><td>sampleSizeByte không phải 2 (16-bit PCM)</td></tr><tr><td>PROVIDER_UNAVAILABLE</td><td>CONFIGURING / STREAMING</td><td>true</td><td>Provider không phản hồi hoặc lỗi tạm thời</td></tr><tr><td>PROVIDER_UNKNOWN</td><td>CONFIGURING / STREAMING</td><td>false</td><td>Provider trả về lỗi không xác định / không ánh xạ được</td></tr><tr><td>SESSION_TIMEOUT</td><td>STREAMING</td><td>false</td><td>Session vượt quá 90 giây</td></tr><tr><td>NO_INPUT_TIMEOUT</td><td>STREAMING</td><td>false</td><td>Không phát hiện âm thanh trong noInputTimeoutMs</td></tr><tr><td>RECOGNIZE_FAILED</td><td>Recognize</td><td>true</td><td>Recognize job thất bại ở provider (thường gặp ở async)</td></tr><tr><td>JOB_NOT_FOUND</td><td>Recognize</td><td>false</td><td>Không tìm thấy transcriptId khi poll /v1/stt/transcripts/:id</td></tr><tr><td>INTERNAL_ERROR</td><td>Bất kỳ</td><td>true</td><td>Lỗi nội bộ không xác định</td></tr></tbody></table>


# Voices


# Get list voices

Lấy thông tin của request bằng cách gọi API

**URL**: <https://vbee.vn/api/public/v1/voices>

**Method**: GET

**Content Type**: application/json

**Response Type**: text/json

**Tham số Header**

| **Tham số**   | **Giá trị**      | **Tính bắt buộc** | **Mô tả**                                                                                                  |
| ------------- | ---------------- | ----------------- | ---------------------------------------------------------------------------------------------------------- |
| Authorization | Bearer {{token}} | Bắt buộc          | Token đại diện cho App gọi API, được sinh ra dưới dạng JWT có thời hạn do lúc khởi tạo App người dùng chọn |
| App-Id        | {{app-id}}       | Bắt buộc          |                                                                                                            |

**PARAMS**

| voice\_ownership | <p>VBEE</p><p>Đơn vị sở hữu giọng đọc. Gồm các giá trị:</p><ul><li>VBEE: giọng đọc của Vbee</li><li>COMMUNITY: giọng cộng đồng</li><li>PERSONAL: giọng của cá nhân người dùng sở hữu</li></ul> |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| code             | <p>hn\_female\_ngochuyen\_full\_48k-fhg</p><p>Mã giọng đọc.</p>                                                                                                                                |
| language\_code   | <p>vi-VN</p><p>Mã ngôn ngữ.</p>                                                                                                                                                                |
| gender           | <p>male</p><p>Giới tính. Gồm giá trị male (giới tính nam) và female (giới tính nữ)</p>                                                                                                         |
| limit            | <p>20</p><p>Số lượng giọng đọc muốn lấy về. Tối thiểu 1, tối đa 100, mặc định 20.</p>                                                                                                          |
| cursor           | <p>WyI2NmE4OTJiNmFhNTBlYmJhMGRjMmQyMmMiXQ==</p><p>Con trỏ dùng để lấy dữ liệu của các trang tiếp theo<br></p>                                                                                  |

**Kết quả trả về** một đối tượng JSON với cấu trúc sau:

* **result**:
  * **pagination**: Đối tượng chứa thông tin phân trang:
    * **has\_next\_page**: Kiểu boolean, cho biết có trang tiếp theo hay không.
    * **has\_prev\_page**: Kiểu boolean, cho biết có trang trước đó hay không.
    * **next\_cursor**: Chuỗi để lấy dữ liệu của trang tiếp theo.
    * **prev\_cursor**: Chuỗi có thể rỗng (nullable) để lấy dữ liệu của trang trước đó.
  * **voices**: Danh sách chi tiết các giọng đọc
    * **code**: Mã giọng đọc.
    * **name**: Tên của giọng đọc.
    * **gender**: Giới tính của giọng đọc.
    * **language\_code**: Mã ngôn ngữ của giọng đọc.
    * **demo**: Audio mẫu của giọng đọc.
    * **credit\_factor**: Hệ số tính "điểm tiêu hao" theo mỗi một ký tự văn bản.
* **status**: Trạng thái yêu cầu. 1 là thành công. 0 là thất bại.

Ngoài ra, bạn cũng có thể tham khảo giọng đọc trực quan trên giao diện AIVoice Studio và lấy mã giọng đọc. Chi tiết xem tại [Hướng dẫn lấy giọng đọc](https://help.vbee.vn/huong-dan-su-dung/chuyen-van-ban/giao-dien-may-tinh/chon-giong-doc)

Danh sách mã ngôn ngữ:\
I'll convert the CSV file to a markdown table for you.Here's the markdown table:

| **code** | **name**              |
| -------- | --------------------- |
| el-GR    | Hy Lạp                |
| kn-IN    | Ấn Độ (Kannada)       |
| pa-IN    | Ấn Độ (Punjabi)       |
| ro-RO    | Rô Man                |
| en-ZA    | Tiếng Anh Nam Phi     |
| es-US    | Tây Ban Nha (Mỹ)      |
| nl-NL    | Hà Lan                |
| en-NZ    | Tiếng Anh New Zealand |
| gu-IN    | Ấn Độ (Gujarati)      |
| ar-XA    | Ả Rập Xê Út           |
| en-GB    | Tiếng Anh (Anh)       |
| it-IT    | Ý                     |
| de-DE    | Đức                   |
| fr-FR    | Pháp                  |
| cmn-CN   | Trung Quốc (Phổn thể) |
| pt-BR    | Bồ Đào Nha (Brazil)   |
| fr-CA    | Pháp (Canada)         |
| en-AU    | Tiếng Anh (Úc)        |
| fil-PH   | Philippines           |
| ru-RU    | Nga                   |
| sr-RS    | Cộng hòa Serbia       |
| tr-TR    | Thổ Nhĩ Kỳ            |
| nl-BE    | Hà Lan (Bỉ)           |
| ko-KR    | Hàn Quốc              |
| bn-IN    | Tây Bengal            |
| sv-SE    | Thụy Điển             |
| yue-HK   | Hồng Kông             |
| cs-CZ    | Cộng hòa Séc          |
| pt-PT    | Bồ Đào Nha            |
| lv-LV    | Cộng hòa Latvia       |
| ca-ES    | Tây Ban Nha (Catalan) |
| ja-JP    | Nhật bản              |
| ms-MY    | Malaysia              |
| pl-PL    | Ba Lan                |
| af-ZA    | Cộng hòa Nam Phi      |
| en-IN    | Tiếng Anh (Ấn)        |
| nb-NO    | Na-Uy                 |
| bg-BG    | Cộng hòa Bulgaria     |
| te-IN    | Ấn Độ (Telugu)        |
| sk-SK    | Cộng hòa Slovakia     |
| da-DK    | Đan Mạch              |
| vi-VN    | Việt Nam              |
| en-US    | Tiếng Anh (Mỹ)        |
| fi-FI    | Phần Lan              |
| ml-IN    | Ấn Độ (Malayalam)     |
| is-IS    | Iceland               |
| hu-HU    | Hungary               |
| id-ID    | Indonesia             |
| ta-IN    | Ấn Độ (Tamil)         |
| es-ES    | Tây Ban Nha           |
| hi-IN    | Ấn Độ (Hindi)         |
| th-TH    | Thái Lan              |
| uk-UA    | Ukraina               |

```
// Example request
curl --location 'https://vbee.vn/api/public/v1/voices?voiceOwnership=VBEE&languageCode=vi-VN' \
--header 'app-id: {{app-id}}'
```

```
// Example response
{
  "result": {
    "pagination": {
      "has_next_page": true,
      "has_prev_page": false,
      "next_cursor": "WyI2NmE4OTJiNmFhNTBlYmJhMGRjMmQyMmMiXQ==",
      "prev_cursor": null
    },
    "voices": [
      {
        "code": "hn_female_ngochuyen_full_48k-fhg",
        "credit_factor": 1,
        "demo": "https://vbee.s3.ap-southeast-1.amazonaws.com/audios/demo/vbee/hn_female_ngochuyen_fast_news_48k-thg.mp3",
        "gender": "female",
        "language_code": "vi-VN",
        "name": "HN - Ngọc Huyền"
      },
      {
        "code": "hn_female_maiphuong_vdts_48k-fhg",
        "credit_factor": 1,
        "demo": "https://vbee.s3.ap-southeast-1.amazonaws.com/audios/demo/vbee/hn_female_maiphuong_vdts_48k_cs-thg.mp3",
        "gender": "female",
        "language_code": "vi-VN",
        "name": "HN - Mai Phương"
      },
      {
        "code": "sg_female_lantrinh_vdts_48k-fhg",
        "credit_factor": 1,
        "demo": "https://vbee.s3.ap-southeast-1.amazonaws.com/audios/demo/vbee/sg_female_lantrinh_fast_vdts_48k_cs-thg.mp3",
        "gender": "female",
        "language_code": "vi-VN",
        "name": "SG - Lan Trinh"
      },
      {
        "code": "hue_female_huonggiang_full_48k-fhg",
        "credit_factor": 1,
        "demo": "https://vbee.s3.ap-southeast-1.amazonaws.com/audios/demo/vbee/hue_female_huonggiang_news_48k_cs-thg.mp3",
        "gender": "female",
        "language_code": "vi-VN",
        "name": "Huế - Hương Giang"
      },
      {
        "code": "sg_female_thaotrinh_full_48k-fhg",
        "credit_factor": 1,
        "demo": "https://vbee.s3.ap-southeast-1.amazonaws.com/audios/demo/vbee/sg_female_thaotrinh_fast_news_48k_cs-thg.mp3",
        "gender": "female",
        "language_code": "vi-VN",
        "name": "SG - Thảo Trinh"
      },
      {
        "code": "sg_male_trungkien_vdts_48k-fhg",
        "credit_factor": 1,
        "demo": "https://vbee.s3.ap-southeast-1.amazonaws.com/audios/demo/vbee/sg_male_trungkien_vdts_48k-fhg.mp3",
        "gender": "male",
        "language_code": "vi-VN",
        "name": "SG - Trung Kiên"
      },
      {
        "code": "hue_male_duyphuong_full_48k-fhg",
        "credit_factor": 1,
        "demo": "https://vbee.s3.ap-southeast-1.amazonaws.com/audios/demo/vbee/sg_female_duyphuong_fast_news_48k_cs-thg.mp3",
        "gender": "male",
        "language_code": "vi-VN",
        "name": "Huế - Duy Phương"
      },
      {
        "code": "sg_male_minhhoang_full_48k-fhg",
        "credit_factor": 1,
        "demo": "https://vbee.s3.ap-southeast-1.amazonaws.com/audios/demo/vbee/sg_male_minhhoang_fast_news_48k_cs-thg.mp3",
        "gender": "male",
        "language_code": "vi-VN",
        "name": "SG - Minh Hoàng"
      },
      {
        "code": "hn_male_manhdung_news_48k-fhg",
        "credit_factor": 1,
        "demo": "https://vbee.s3.ap-southeast-1.amazonaws.com/audios/demo/vbee/hn_male_manhdung_news_48k_cs-thg.mp3",
        "gender": "male",
        "language_code": "vi-VN",
        "name": "HN - Mạnh Dũng"
      },
      {
        "code": "hn_male_thanhlong_talk_48k-fhg",
        "credit_factor": 1,
        "demo": "https://vbee.s3.ap-southeast-1.amazonaws.com/audios/demo/vbee/hn_male_thanhlong_talk_48k-fhg.mp3",
        "gender": "male",
        "language_code": "vi-VN",
        "name": "HN - Thanh Long"
      },
      {
        "code": "hn_male_phuthang_news65dt_44k-fhg",
        "credit_factor": 1,
        "demo": "https://vbee.s3.ap-southeast-1.amazonaws.com/audios/demo/vbee/hn_male_phuthang_news65dt_44k-fhg.mp3",
        "gender": "male",
        "language_code": "vi-VN",
        "name": "HN - Anh Khôi"
      },
      {
        "code": "sg_female_tuongvy_call_44k-fhg",
        "credit_factor": 1,
        "demo": "https://vbee.s3.ap-southeast-1.amazonaws.com/audios/demo/vbee/sg_female_tuongvy_call_44k-fhg.mp3",
        "gender": "female",
        "language_code": "vi-VN",
        "name": "SG - Tường Vy"
      },
      {
        "code": "sg_female_thaotrinh_full_44k-phg",
        "credit_factor": 1,
        "demo": "https://vbee.s3.ap-southeast-1.amazonaws.com/audios/demo/vbee/sg_female_thaotrinh_full_44k-phg.mp3",
        "gender": "female",
        "language_code": "vi-VN",
        "name": "SG - Thảo Trinh"
      },
      {
        "code": "hn_male_manhdung_news_48k-phg",
        "credit_factor": 1,
        "demo": "https://vbee.s3.ap-southeast-1.amazonaws.com/audios/demo/vbee/hn_male_manhdung_news_48k-phg.mp3",
        "gender": "male",
        "language_code": "vi-VN",
        "name": "HN - Mạnh Dũng"
      },
      {
        "code": "hn_male_phuthang_stor80dt_48k-fhg",
        "credit_factor": 1,
        "demo": "https://vbee.s3.ap-southeast-1.amazonaws.com/audios/demo/vbee/hn_male_phuthang_stor80dt_48k-fhg.mp3",
        "gender": "male",
        "language_code": "vi-VN",
        "name": "HN - Anh Khôi"
      },
      {
        "code": "hn_female_hermer_stor_48k-fhg",
        "credit_factor": 1,
        "demo": "https://vbee.s3.ap-southeast-1.amazonaws.com/audios/demo/vbee/hn_female_hermer_stor_48k-fhg.mp3",
        "gender": "female",
        "language_code": "vi-VN",
        "name": "HN - Ngọc Lan"
      },
      {
        "code": "hn_female_lenka_stor_48k-phg",
        "credit_factor": 1,
        "demo": "https://vbee.s3.ap-southeast-1.amazonaws.com/audios/demo/vbee/hn_female_lenka_stor_48k-phg.wav",
        "gender": "female",
        "language_code": "vi-VN",
        "name": "HN - Nguyệt Dương"
      },
      {
        "code": "sg_male_chidat_ebook_48k-phg",
        "credit_factor": 1,
        "demo": "https://vbee.s3.ap-southeast-1.amazonaws.com/audios/demo/vbee/sg_male_chidat_ebook_48k-phg.wav",
        "gender": "male",
        "language_code": "vi-VN",
        "name": "SG - Chí Đạt"
      },
      {
        "code": "hn_female_hachi_book_22k-vc",
        "credit_factor": 1,
        "demo": "https://vbee.s3.ap-southeast-1.amazonaws.com/audios/demo/vbee/hn_female_hachi_book_22k-vc.mp3",
        "gender": "female",
        "language_code": "vi-VN",
        "name": "HN - Hà Chi"
      },
      {
        "code": "hn_male_vietbach_child_22k-vc",
        "credit_factor": 1,
        "demo": "https://vbee.s3.ap-southeast-1.amazonaws.com/audios/demo/vbee/hn_male_vietbach_child_22k-vc.mp3",
        "gender": "male",
        "language_code": "vi-VN",
        "name": "HN - Việt Bách"
      }
    ]
  },
  "status": 1
}
```


# Text to Speech (Lagacy)


# Create speech

**URL**: <https://vbee.vn/api/v1/tts>

**Method**: POST

**Content Type**: application/json

**Response Type**: text/json

**Tham số Header**

<table data-header-hidden><thead><tr><th></th><th width="187"></th><th></th><th></th></tr></thead><tbody><tr><td><strong>Tham số</strong></td><td><strong>Giá trị</strong></td><td><strong>Tính bắt buộc</strong></td><td><strong>Mô tả</strong></td></tr><tr><td>Authorization</td><td>Bearer {{token}}</td><td>Bắt buộc</td><td>Token đại diện cho App gọi API, được sinh ra dưới dạng JWT có thời hạn do lúc khởi tạo App người dùng chọn</td></tr></tbody></table>

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

| **Tham số**         | **Kiểu dữ liệu** | **Tính bắt buộc**                          | **Mô tả**                                                                                                                                                                                                                                                                                     |
| ------------------- | ---------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| app\_id             | String           | Bắt buộc                                   | ID của ứng dụng, được sinh ra khi khởi tạo App                                                                                                                                                                                                                                                |
| response\_type      | String           | Có                                         | Giá trị: indirect                                                                                                                                                                                                                                                                             |
| callback\_url       | String           | Bắt buộc                                   | Webhook để nhận kết quả của request                                                                                                                                                                                                                                                           |
| input\_text         | String           | Tùy chọn (Bắt buộc khi không có sentences) | Văn bản đầu vào cần tổng hợp                                                                                                                                                                                                                                                                  |
| voice\_code         | String           | Tùy (Bắt buộc khi có input\_text)          | Mã giọng đọc cần tổng hợp                                                                                                                                                                                                                                                                     |
| audio\_type         | String           | Tùy chọn                                   | <p>Định dạng loại file audio đầu ra</p><p>\* Giá trị mặc định: mp3</p><p>\* Giá trị audio\_type cho phép truyền vào là: mp3, wav</p>                                                                                                                                                          |
| bitrate             | Number           | <p><br></p>                                | <p>Dùng để chuyển đầu ra về bit rate (bps) mong muốn</p><p>\* Giá trị mặc định: 128</p><p>\* Giá trị bit\_rate cho phép truyền vào là: 8, 16, 32, 64, 128.</p><p>\* Lưu ý: giá trị tham số bit\_rate chỉ có ý nghĩa khi audio\_type=mp3</p>                                                   |
| speed\_rate         | Number           | Tùy chọn                                   | <p>Dùng để điều chỉnh tốc độ của giọng đọc</p><p>\* Giá trị mặc định: 1.0</p><p>\* Giá trị của tham số speed\_rate có thể chạy từ 0.1 đến 1.9 và chấp nhận 1 chứ số sau dấu thập phân</p>                                                                                                     |
| sample\_rate        | Number           | Tùy chọn                                   | <p>Dùng để điều chỉnh sample rate mong muốn</p><p>\* Giá trị của tham số sample\_rate phụ thuộc vào từng giọng</p>                                                                                                                                                                            |
| emphasis\_intensity | Number           | Tùy chọn                                   | <p>Dùng để điều chỉnh mức độ nhấn nhá.</p><p>Giá trị của tham số từ 0 - 100 và phải là bội số của 10.</p><p>Lưu ý: Tham số này chỉ áp dụng với giọng có hỗ trợ chức năng nhấn nhá. Giọng nhấn nhá là giọng đọc có field "has\_emphasis" trong kết quả trả về của API lấy danh sách giọng.</p> |

**Chú ý:**

***Các audio link trả về chỉ có thời hạn trong vòng 3 phút, sau 3 phút audio link sẽ hết hạn và không thể sử dụng. Audio vẫn sẽ được lưu trữ trên hệ thống trong vòng 3 ngày kể từ thời điểm chuyển văn bản thành công. Muốn lấy link mới, bạn gọi api Get Request (bên dưới) để lấy lại audio link mới.***

**Kết quả trả về**

* **status**: trạng thái của API (1: thành công, 0: thất bại)
* **error\_code**: mã lỗi
* **error\_message**: chi tiết lỗi
* **result**: dữ liệu trả về khi gọi API thành công
  * app\_id
  * request\_id: mã request
  * characters: số ký tự của đoạn văn bản convert
  * voice\_code
  * audio\_type
  * speed\_rate
  * sample\_rate
  * bitrate
  * create\_at
  * status: trạng thái của request (IN\_PROGRESS)

```
// Example request
curl --location 'https://vbee.vn/api/v1/tts' \
--data '{
    "app_id": "55e0053d-f86f-4c2b-b791-b1ba6d59a868",
    "response_type": "indirect",
    "callback_url": "https://mydomain/callback",
    "input_text": "Chào mừng đén với website của chúng tôi! Đây là trang web cung cấp một giải pháp văn bản thành giọng nói, trên cơ sở, nó hỗ trợ các doanh nghiệp xây dựng các hệ thống trung tâm cuộc gọi tự động, hệ thống thông báo công khai, trợ lý ảo, tin tức âm thanh, podcast, sách âm thanh và tường thuật phim.",
    "voice_code": "hn_female_ngochuyen_full_48k-fhg",
    "audio_type":"mp3",
    "bitrate": 128,
    "speed_rate": "1.0"
}'
```

```
// Example response
{
  "result": {
    "app_id": "55e0053d-f86f-4c2b-b791-b1ba6d59a868",
    "audio_type": "mp3",
    "bitrate": 128,
    "characters": 297,
    "request_id": "5509d1e6-8906-4291-899b-c25643a624af",
    "speed_rate": "1.0",
    "status": "IN_PROGRESS",
    "voice_code": "hn_female_ngochuyen_full_48k-fhg"
  },
  "status": 1
}
```


# Callback API

Khi request thành công, hệ thống VBEE TTS sẽ gửi đến Callback URL một HTTP POST như sau

**URL**: callback url truyền lên khi gọi API Create speech

**Method**: POST

**Content Type**: application/json

**Body**:

| Thuộc tính   | Kiểu dữ liệu | Mô tả                                                                                 |
| ------------ | ------------ | ------------------------------------------------------------------------------------- |
| app\_id      | String       | ID của ứng dụng                                                                       |
| request\_id  | String       | ID của request                                                                        |
| characters   | Number       | Số ký tự của đoạn văn bản                                                             |
| voice\_code  | String       | Mã giọng                                                                              |
| audio\_type  | String       | Định dạng file audio đầu ra                                                           |
| speed\_rate  | Number       | Tốc độ đọc                                                                            |
| sample\_rate | String       | Sample rate của audio đầu ra                                                          |
| bitrate      | Number       | Bitrate của file audio đầu ra                                                         |
| created\_at  | String       | Thời gian khởi tạo request                                                            |
| status       | String       | <p>Trạng thái của request</p><p>\* SUCCESS: Thành công</p><p>\* FAILURE: Thất bại</p> |
| audio\_link  | String       | Đường dẫn tải file audio tổng hợp                                                     |

```
//Example request
{
    "app_id": "{{app_id}}",
    "response_type": "indirect",
    "callback_url": "https://mydomain/callback",
    "input_text": "Xin Chào mừng đén với website của chúng tôi! Đây là trang web cung cấp một giải pháp văn bản thành giọng nói, trên cơ sở, nó hỗ trợ các doanh nghiệp xây dựng các hệ thống trung tâm cuộc gọi tự động, hệ thống thông báo công khai, trợ lý ảo, tin tức âm thanh, podcast, sách âm thanh và tường thuật phim.",
    "voice_code": "hn_female_ngochuyen_full_48k-fhg",
    "audio_type":"mp3",
    "bitrate": 128,
    "speed_rate": "1.0"
}

```


# Get Request

Lấy thông tin của request bằng cách gọi API

**URL**: [https://vbee.vn/api/v1/tts/{request\_id}](https://vbee.vn/api/v1/tts/%7Brequest_id%7D)

**Method**: GET

**Content Type**: application/json

**Response Type**: text/json

**Tham số Header**

| **Tham số**   | **Giá trị**      | **Tính bắt buộc** | **Mô tả**                                                                                                  |
| ------------- | ---------------- | ----------------- | ---------------------------------------------------------------------------------------------------------- |
| Authorization | Bearer {{token}} | Bắt buộc          | Token đại diện cho App gọi API, được sinh ra dưới dạng JWT có thời hạn do lúc khởi tạo App người dùng chọn |

**Kết quả trả về**

* **status**: trạng thái của API (1: thành công, 0: thất bại)
* **error\_code**: mã lỗi
* **error\_message**: chi tiết lỗi
* **result**: dữ liệu trả về khi gọi API thành công
  * app\_id
  * request\_id: mã request
  * characters: số ký tự của đoạn văn bản convert
  * voice\_code
  * audio\_type
  * speed\_rate
  * bitrate
  * create\_at
  * progress: phần trăm xử lý của request
  * status: trạng thái của request
  * audio\_link: Đường dẫn tải file audio tổng hợp
  * audio\_expired: trạng thái của audio, true nếu audio đã hết hạn lưu trữ

```
// Example request
curl --location 'https://vbee.vn/api/v1/tts/9bc63cb3-7c80-4e61-8cda-7c7391a21bbe'
```

```
// Example response
{
  "result": {
    "app_id": "b5cdad60-6637-4061-98e4-aa9a3ba80932",
    "audio_link": "https://vbee.vn/s/112002fd-cbd2-4a28-5089-204a0580175b/4c0a038b-2f63-5683-8795-518c25f83d86",
    "audio_type": "wav",
    "bitrate": 128,
    "characters": 4874,
    "request_id": "9bc63cb3-7c80-4e61-8cda-7c7391a21bbe",
    "speed_rate": 1,
    "status": "SUCCESS",
    "voice_code": "hn_female_maiphuong_vdts_48k-fhg"
  },
  "status": 1
}
```


# Get Callback Result

Lấy thông tin kết quả gọi callback của request (chỉ áp dụng với request dạng callback)

**URL**: [https://vbee.vn/api/v1/tts/{request\_id}/callback-result](https://vbee.vn/api/v1/tts/%7Brequest_id%7D/callback-result)

**Method**: GET

**Content Type**: application/json

**Response Type**: text/json

**Tham số Header**

| **Tham số**   | **Giá trị**      | **Tính bắt buộc** | **Mô tả**                                                                                                  |
| ------------- | ---------------- | ----------------- | ---------------------------------------------------------------------------------------------------------- |
| Authorization | Bearer {{token}} | Bắt buộc          | Token đại diện cho App gọi API, được sinh ra dưới dạng JWT có thời hạn do lúc khởi tạo App người dùng chọn |

**Kết quả trả về**

* **status**: trạng thái của API (1: thành công, 0: thất bại)
* **error\_code**: mã lỗi
* **error\_message**: chi tiết lỗi
* **result**: dữ liệu trả về khi gọi API thành công
  * request\_id: ID của request
  * callback\_url: Webhook để nhận kết quả của request
  * created\_at: Thời gian gọi callback
  * payload: Dữ liệu gửi đi khi gọi callback
  * status\_code: Mã code nhận về khi gọi callback
  * result: Kết quả nhận về khi gọi callback

```
// Example request
curl --location 'https://vbee.vn/api/v1/tts/4fbe1c92-527a-4a31-841e-8f1e6e8d040b/callback-result'
```

```
// Example response
{
  "result": {
    "callback_url": "https://edfe-42-117-19-3.ngrok.io/callback",
    "created_at": "2022-08-12T07:18:54.479Z",
    "payload": {
      "app_id": "abc2baa6-b848-4014-8584-03812870fc28",
      "audio_link": "https://vbee.vn/s/112002fd-cbd2-4a28-5089-204a0580175b/4c0a038b-2f63-5683-8795-518c25f83d86",
      "audio_type": "wav",
      "bitrate": 128,
      "characters": 16,
      "created_at": "2022-08-12T07:18:51.890Z",
      "request_id": "4fbe1c92-527a-4a31-841e-8f1e6e8d040b",
      "sample_rate": "44100",
      "speed_rate": 1,
      "status": "SUCCESS",
      "voice_code": "hn_female_ngochuyen_full_48k-fhg"
    },
    "request_id": "4fbe1c92-527a-4a31-841e-8f1e6e8d040b",
    "result": "OK",
    "status_code": "200"
  },
  "status": 1
}

```