> 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/speech-to-text/batch-api.md).

# 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
}

```