# BVoiz MCP Server 🎙️

[![Node.js Version](https://img.shields.io/badge/Node.js-%3E%3D18.0.0-green.svg)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)
[![Model Context Protocol](https://img.shields.io/badge/MCP-1.6.1-orange.svg)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

> **Model Context Protocol (MCP)** server chính thức cho nền tảng âm thanh AI **BVoiz** ([https://bvoiz.com](https://bvoiz.com)).  
> Giúp các AI Agent như **Claude (Desktop & Code)**, **OpenAI Codex / ChatGPT**, **Google Antigravity**, **Cursor**, **Windsurf**, **VS Code Copilot** dễ dàng tích hợp khả năng sinh giọng đọc tiếng Việt truyền cảm số một (Text-to-Speech), nhân bản giọng nói (Voice Cloning) và tự động hóa xử lý âm thanh vào các quy trình phát triển phần mềm.

---

## 📑 Mục lục

1. [Giới thiệu](#-giới-thiệu)
2. [Kiến trúc hệ thống](#-kiến-trúc-hệ-thống)
3. [Tính năng nổi bật](#-tính-năng-nổi-bật)
4. [Yêu cầu hệ thống & Cài đặt](#-yêu-cầu-hệ-thống--cài-đặt)
5. [Hướng dẫn cấu hình cho từng AI Agent](#-hướng-dẫn-cấu-hình-cho-từng-ai-agent)
   - [Claude Desktop](#1-claude-desktop)
   - [Cursor AI Editor](#2-cursor-ai-editor)
   - [Claude Code (CLI)](#3-claude-code-cli)
   - [Google Antigravity](#4-google-antigravity)
   - [Windsurf / Codeium](#5-windsurf--codeium)
   - [VS Code Copilot / Cline / Roo Code](#6-vs-code-copilot--cline--roo-code)
6. [Danh mục 14 MCP Tools chi tiết](#-danh-mục-14-mcp-tools-chi-tiết)
7. [MCP Resources & Prompts](#-mcp-resources--prompts)
8. [Bảng mã giọng đọc BVoiz phổ biến (Cheat Sheet)](#-bảng-mã-giọng-đọc-bvoiz-phổ-biến-cheat-sheet)
9. [Kịch bản thực tế AI Agent có thể thực hiện](#-kịch-bản-thực-tế-ai-agent-có-thể-thực-hiện)
10. [Xử lý sự cố thường gặp (FAQ & Troubleshooting)](#-xử-lý-sự-cố-thường-gặp-faq--troubleshooting)
11. [Hỗ trợ & Bản quyền](#-hỗ-trợ--bản-quyền)

---

## 📖 Giới thiệu

**BVoiz** ([https://bvoiz.com](https://bvoiz.com)) là nền tảng AI Voice hàng đầu tại Việt Nam, sở hữu công nghệ tổng hợp giọng nói tiếng Việt tự nhiên, có hồn, giàu cảm xúc với hơn 36+ diễn viên lồng tiếng AI đa vùng miền (Bắc, Trung, Nam) cùng khả năng nhân bản giọng nói chỉ với 5–15 giây mẫu thu.

**BVoiz MCP Server** đóng vai trò cầu nối chuẩn hóa quốc tế (theo chuẩn giao thức mã nguồn mở **Model Context Protocol** do Anthropic khởi xướng), cho phép các mô hình ngôn ngữ lớn (LLM) và trợ lý lập trình thông minh có thể **trực tiếp gọi API BVoiz** như một tập hợp các công cụ (tools), tài nguyên (resources) và kịch bản gợi ý (prompts) có sẵn.

---

## 🏗️ Kiến trúc hệ thống

```mermaid
flowchart LR
    subgraph AI_Clients ["Các AI Agent & IDEs"]
        Claude["Claude Desktop / Claude Code"]
        Cursor["Cursor AI"]
        Antigravity["Google Antigravity"]
        Windsurf["Windsurf / Codeium"]
        Codex["OpenAI Codex / ChatGPT"]
    end

    subgraph MCP_Server ["BVoiz MCP Server (Node.js/TypeScript)"]
        Transport["Stdio Transport (JSON-RPC 2.0)"]
        Tools["14 Tools: TTS, Voice Cloning, Jobs, Voices"]
        Resources["Resources: bvoiz://voices, account, pricing"]
        Prompts["Prompts: bvoiz_script_polisher, recommend"]
        Client["BVoizApiClient (Polling queue, multipart, cache)"]
    end

    subgraph BVoiz_Cloud ["BVoiz Cloud Platform (https://bvoiz.com)"]
        TTS_API["/api/tts & /api/tts/demo"]
        Clone_API["/api/clone"]
        Voices_API["/api/tts/voices"]
        Storage["Cloudflare R2 Storage CDN"]
    end

    AI_Clients <-->|MCP Protocol / stdio| Transport
    Transport --> Tools & Resources & Prompts
    Tools & Resources & Prompts --> Client
    Client <-->|REST API + Bearer Token| TTS_API & Clone_API & Voices_API
    TTS_API & Clone_API --> Storage
```

---

## 🌟 Tính năng nổi bật

- 🗣️ **Chuyển văn bản thành giọng nói (TTS) chất lượng cao**:
  - Hỗ trợ đầy đủ các tham số chuyên nghiệp: tốc độ (`speed`), cao độ (`pitch`), âm lượng (`volume`), định dạng âm thanh (`mp3` / `wav`).
  - Hơn 36+ giọng đọc AI tiếng Việt đa dạng vùng miền (Bắc, Trung, Nam) và đa ngôn ngữ.
- 💾 **Tự động lưu file âm thanh về máy cục bộ (`save_to_file`)**:
  - AI Agent có thể trực tiếp sinh audio và lưu ngay vào thư mục làm việc cục bộ (ví dụ: `E:/videos/audio_voiceover.mp3`) mà không cần lập trình viên phải viết thêm code trung gian để tải file.
- ⚡ **Thử nghiệm miễn phí không cần API Key (`bvoiz_demo_synthesize`)**:
  - Cho phép người dùng và AI Agent thử nghiệm bất kỳ giọng đọc nào với các đoạn văn bản ngắn (tối đa 300 ký tự) hoàn toàn MIỄN PHÍ, không tiêu hao credits.
- 🧬 **Nhân bản giọng nói tức thì (Instant Voice Cloning)**:
  - Tải lên file âm thanh giọng nói mẫu (5–15 giây) trực tiếp từ ổ cứng để huấn luyện và đăng ký một giọng đọc nhân bản độc quyền trong tài khoản.
- ⏳ **Tự động xử lý hàng đợi cho văn bản dài (Async Queue Polling)**:
  - Tự động nhận diện phản hồi HTTP 202 (xử lý nền), tự động thăm dò (polling) hàng đợi cho đến khi hoàn tất và trả về file âm thanh thành phẩm.
- 🔍 **Tìm kiếm giọng đọc thông minh bằng ngôn ngữ tự nhiên**:
  - Tìm kiếm giọng theo ngữ cảnh ứng dụng: *"kể chuyện đêm khuya"*, *"review phim"*, *"tin tức trang trọng"*, *"quảng cáo TVC hào sảng"*, *"tổng đài chăm sóc khách hàng"*.
- 📊 **Kiểm tra tài khoản & Lịch sử**:
  - Tra cứu số dư credits thời gian thực, lịch sử các lần chuyển đổi âm thanh và bảng giá các gói cước.

---

## 💻 Yêu cầu hệ thống & Cài đặt

### 1. Yêu cầu môi trường
- **Node.js**: Phiên bản `>= 18.0.0` (Khuyến nghị Node.js v20 hoặc v22).
- **Hệ điều hành**: Windows, macOS, hoặc Linux.

### 2. Cài đặt mã nguồn

```bash
# 1. Clone repository về máy tính của bạn
git clone https://github.com/TraudioDev/bvoiz-mcp.git

# 2. Di chuyển vào thư mục dự án
cd bvoiz-mcp

# 3. Cài đặt các gói phụ thuộc
npm install

# 4. Biên dịch mã nguồn TypeScript sang JavaScript
npm run build
```

Sau khi build, file thực thi chính sẽ nằm tại:
- **Windows**: `E:\Git\bvoiz-mcp\dist\index.js` (hoặc đường dẫn thư mục bạn đã clone)
- **macOS/Linux**: `/path/to/bvoiz-mcp/dist/index.js`

### 3. Lấy BVoiz API Key
1. Đăng nhập vào trang chủ BVoiz: [https://bvoiz.com](https://bvoiz.com)
2. Vào trang quản lý tài khoản: [https://bvoiz.com/account](https://bvoiz.com/account)
3. Tại mục **Tích hợp API**, chọn **Tạo API Key**. Bạn sẽ nhận được một chuỗi khóa có định dạng: `bv_live_xxxxxxxxxxxxxxxxxxxxxxxx`
4. Copy và lưu lại API Key của bạn để cấu hình cho Agent.

*(Mẹo: Bạn vẫn có thể dùng các chức năng xem giọng và thử giọng miễn phí `bvoiz_demo_synthesize` ngay cả khi chưa có API Key).*

---

## ⚙️ Hướng dẫn cấu hình cho từng AI Agent

### 1. Claude Desktop

Mở file cấu hình của Claude Desktop:
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

Thêm khối cấu hình `bvoiz` vào mục `mcpServers`:

```json
{
  "mcpServers": {
    "bvoiz": {
      "command": "node",
      "args": ["E:\\Git\\bvoiz-mcp\\dist\\index.js"],
      "env": {
        "BVOIZ_API_KEY": "bv_live_your_actual_api_key_here"
      }
    }
  }
}
```

> **Ghi chú trên macOS/Linux**: Thay đường dẫn thành dạng Unix: `"/Users/username/bvoiz-mcp/dist/index.js"`.  
> Khởi động lại Claude Desktop, bạn sẽ thấy biểu tượng chiếc búa 🔨 xuất hiện ở góc dưới khung chat với đầy đủ 14 công cụ BVoiz!

---

### 2. Cursor AI Editor

Bạn có thể cấu hình thông qua file cấu hình hoặc giao diện đồ họa của Cursor:

#### Cách 1: Thêm vào file `.cursor/mcp.json` trong thư mục dự án của bạn

Tạo file `.cursor/mcp.json` tại thư mục gốc của project:

```json
{
  "mcpServers": {
    "bvoiz": {
      "command": "node",
      "args": ["E:\\Git\\bvoiz-mcp\\dist\\index.js"],
      "env": {
        "BVOIZ_API_KEY": "bv_live_your_actual_api_key_here"
      }
    }
  }
}
```

#### Cách 2: Qua giao diện Cursor Settings
1. Mở Cursor -> Bấm vào biểu tượng bánh răng **Settings** (góc trên bên phải).
2. Chọn thẻ **Features** -> cuộn xuống mục **MCP Servers**.
3. Bấm **Add New MCP Server**:
   - **Name**: `bvoiz`
   - **Type**: `command`
   - **Command**: `node E:\Git\bvoiz-mcp\dist\index.js`
4. Trong ô Composer hoặc Chat của Cursor, gõ `@bvoiz` để kích hoạt công cụ.

---

### 3. Claude Code (CLI)

Chạy lệnh thêm MCP trực tiếp qua terminal:

```bash
claude mcp add bvoiz node E:\Git\bvoiz-mcp\dist\index.js -e BVOIZ_API_KEY=bv_live_your_api_key
```

Kiểm tra trạng thái kết nối:
```bash
claude mcp list
```

---

### 4. Google Antigravity

Trong cấu hình cài đặt MCP server của Antigravity (`~/.gemini/antigravity/settings.json` hoặc cấu hình Workspace):

```json
{
  "mcpServers": {
    "bvoiz": {
      "command": "node",
      "args": ["E:\\Git\\bvoiz-mcp\\dist\\index.js"],
      "env": {
        "BVOIZ_API_KEY": "bv_live_your_actual_api_key_here"
      }
    }
  }
}
```

---

### 5. Windsurf / Codeium

Mở file cấu hình MCP của Windsurf tại `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "bvoiz": {
      "command": "node",
      "args": ["E:\\Git\\bvoiz-mcp\\dist\\index.js"],
      "env": {
        "BVOIZ_API_KEY": "bv_live_your_actual_api_key_here"
      }
    }
  }
}
```

---

### 6. VS Code Copilot / Cline / Roo Code

Mở cài đặt extension MCP trong VS Code (hoặc file cấu hình `cline_mcp_settings.json`):

```json
{
  "mcpServers": {
    "bvoiz": {
      "command": "node",
      "args": ["E:\\Git\\bvoiz-mcp\\dist\\index.js"],
      "env": {
        "BVOIZ_API_KEY": "bv_live_your_actual_api_key_here"
      },
      "disabled": false,
      "autoApprove": [
        "bvoiz_synthesize_speech",
        "bvoiz_demo_synthesize",
        "bvoiz_list_voices",
        "bvoiz_search_voices",
        "bvoiz_download_audio"
      ]
    }
  }
}
```

---

## 🛠️ Danh mục 14 MCP Tools chi tiết

| Tên công cụ (Tool Name) | Phân loại | Mô tả tóm tắt |
| :--- | :--- | :--- |
| `bvoiz_synthesize_speech` | 🗣️ TTS chính | Chuyển văn bản thành giọng đọc AI tự nhiên, hỗ trợ lưu file tự động về máy. |
| `bvoiz_demo_synthesize` | ⚡ Demo miễn phí | Thử giọng miễn phí tối đa 300 ký tự (không cần API key hay credits). |
| `bvoiz_download_audio` | 💾 Tải âm thanh | Tải bất kỳ file âm thanh nào từ BVoiz về ổ đĩa cục bộ. |
| `bvoiz_get_job_status` | ⏳ Quản lý tiến trình | Kiểm tra tiến độ tác vụ tạo âm thanh nền cho các bài đọc dài. |
| `bvoiz_list_voices` | 🔍 Khám phá giọng | Liệt kê các giọng đọc AI theo ngôn ngữ, giới tính, vùng miền, nhà cung cấp. |
| `bvoiz_search_voices` | 🎯 Tìm kiếm giọng | Tìm kiếm giọng đọc bằng từ khóa cảm xúc, thể loại video, phong cách. |
| `bvoiz_get_voice_details` | ℹ️ Chi tiết giọng | Xem đầy đủ thông tin, link nghe mẫu của một giọng đọc theo ID. |
| `bvoiz_clone_voice` | 🧬 Nhân bản giọng | Tạo giọng nhân bản mới từ file audio 5–15s trên máy cục bộ. |
| `bvoiz_list_cloned_voices` | 🧬 Danh sách clone | Xem danh sách các giọng nhân bản cá nhân của tài khoản. |
| `bvoiz_test_cloned_voice` | 🧬 Thử giọng clone | Đọc thử một câu văn bản bằng giọng đã nhân bản. |
| `bvoiz_delete_cloned_voice` | 🗑️ Xóa giọng clone | Xóa một giọng nhân bản khỏi tài khoản. |
| `bvoiz_get_account` | 👤 Tài khoản | Xem số dư credits, email, gói thành viên hiện tại. |
| `bvoiz_get_history` | 📜 Lịch sử | Lấy danh sách lịch sử các lần chuyển đổi giọng nói gần nhất. |
| `bvoiz_get_pricing_plans` | 💳 Bảng giá | Xem bảng giá các gói cước credits và hướng dẫn nạp VietQR. |

---

### Chi tiết các công cụ trọng tâm

#### 1. `bvoiz_synthesize_speech`
Chuyển đổi văn bản thành giọng nói tiếng Việt/đa ngôn ngữ.

**Tham số:**
- `text` *(string, bắt buộc)*: Nội dung văn bản cần đọc.
- `speaker_id` *(string, tùy chọn)*: ID giọng đọc (ví dụ: `bvoiz_nam_mb_muu_luoc`, `bvoiz_nu_mn_ngan_nguyen_sang_trong`).
- `speed` *(number, tùy chọn, mặc định 1.0)*: Tốc độ đọc từ 0.5 (chậm) đến 2.0 (nhanh).
- `pitch` *(number, tùy chọn, mặc định 1.0)*: Cao độ từ 0.5 (trầm) đến 1.5 (cao).
- `volume` *(number, tùy chọn, mặc định 100)*: Âm lượng từ 0 đến 100.
- `audio_type` *(string, tùy chọn, mặc định 'mp3')*: Định dạng `'mp3'` hoặc `'wav'`.
- `save_to_file` *(string, tùy chọn)*: Đường dẫn lưu file trực tiếp trên máy cục bộ (ví dụ: `E:/output.mp3`).
- `async` *(boolean, tùy chọn, mặc định false)*: Chế độ nền trả về Job ID ngay cho văn bản dài.
- `api_key` *(string, tùy chọn)*: Ghi đè API key nếu chưa cài biến môi trường.

**Ví dụ trả về:**
```json
{
  "success": true,
  "request_id": "1793101361_65189ec778e6df2f",
  "speaker_name": "Bá Kiên (Mưu Lược & Kịch Tính)",
  "audio_url": "https://bvoiz.com/storage/audio/1793101361_65189ec778e6df2f.mp3",
  "r2_url": "https://bvoiz.com/storage/r2/user-voices/2026-10-27/1793101361_65189ec778e6df2f.mp3",
  "char_count": 47,
  "duration_sec": 3.2,
  "file_size_bytes": 48813,
  "local_file_path": "E:/output.mp3"
}
```

---

#### 2. `bvoiz_clone_voice`
Tạo một giọng nói nhân bản từ file âm thanh mẫu có sẵn trên máy tính của bạn.

**Tham số:**
- `name` *(string, bắt buộc)*: Tên đặt cho giọng nói nhân bản (ví dụ: `Giong_Doc_Cua_Toi`).
- `audio_file_path` *(string, bắt buộc)*: Đường dẫn đến file âm thanh mẫu (WAV, MP3, M4A, FLAC, 5–15 giây thu âm rõ ràng, không lẫn tạp âm).
- `gender` *(enum: 'Nam' | 'Nữ', tùy chọn, mặc định 'Nam')*: Giới tính giọng đọc.
- `ref_text` *(string, tùy chọn)*: Nội dung câu nói có trong đoạn mẫu để hệ thống căn chỉnh âm chuẩn xác hơn.

---

## 📚 MCP Resources & Prompts

### 1. Resources (Tài nguyên đọc ngữ cảnh)
AI Agent có thể đọc dữ liệu trực tiếp từ các URI sau mà không cần tốn lượt gọi tool:
- `bvoiz://voices`: Danh mục dữ liệu JSON toàn bộ giọng đọc đang có trên hệ thống BVoiz.
- `bvoiz://account`: Dữ liệu số dư credits và tài khoản BVoiz hiện tại.
- `bvoiz://pricing`: Bảng giá và hạn mức các gói cước dịch vụ.

### 2. Prompts (Kịch bản hỗ trợ)
- **`bvoiz_script_polisher`**: Tự động biên tập lại kịch bản văn bản thô:
  - Thêm dấu phẩy `,` và dấu chấm `.` tại các khoảng nghỉ lấy hơi tự nhiên.
  - Phiên âm các từ viết tắt tiếng Việt (`TP.HCM` -> `Thành phố Hồ Chí Minh`, `VNĐ` -> `đồng`).
  - Viết chữ cho các con số, năm, ngày tháng để máy đọc tự nhiên.
- **`bvoiz_recommend_voice`**: Tư vấn giọng đọc:
  - Nhập vào thể loại video, đối tượng khán giả, phong cách mong muốn.
  - AI phân tích và đề xuất 2-3 mã giọng đọc tối ưu kèm thông số tốc độ, cao độ phù hợp nhất.

---

## 🎭 Bảng mã giọng đọc BVoiz phổ biến (Cheat Sheet)

| Speaker ID | Tên giọng đọc | Giới tính | Vùng miền | Thể loại phù hợp nhất |
| :--- | :--- | :--- | :--- | :--- |
| `bvoiz_nam_mb_muu_luoc` | Bá Kiên | Nam | Miền Bắc | Tài liệu, Lịch sử, Cổ trang, Kịch tính, Mưu lược |
| `bvoiz_nu_mn_ngan_nguyen_sang_trong` | Ngân Nguyễn | Nữ | Miền Nam | TVC Quảng cáo, Giới thiệu thương hiệu sang trọng |
| `bvoiz_nam_mb_phat_trien_ban_than` | Tuấn Khang | Nam | Miền Bắc | Podcast, Sách nói Self-Help, Truyền cảm hứng |
| `bvoiz_nu_mb_ha_linh_diu_dang` | Hà Linh | Nữ | Miền Bắc | Tâm sự đêm khuya, Kể chuyện cổ tích, Thơ ca |
| `bvoiz_nam_mn_tan_tai_hao_sang` | Tấn Tài | Nam | Miền Nam | Review ẩm thực, Du lịch, Vlog đời sống miền Tây |
| `bvoiz_nu_mt_thao_vy` | Thảo Vy | Nữ | Miền Trung | Thuyết minh phóng sự miền Trung, Phim tài liệu |
| `vi-VN-HoaiMyNeural` | Hoài My | Nữ | Miền Bắc | Tin tức thời sự, Bài giảng điện tử, Tổng đài IVR |
| `vi-VN-NamMinhNeural` | Nam Minh | Nam | Miền Bắc | Bản tin kinh tế, Hướng dẫn kỹ thuật, Chăm sóc KH |

---

## 💡 Kịch bản thực tế AI Agent có thể thực hiện

Sau khi kết nối BVoiz MCP, bạn có thể ra lệnh trực tiếp bằng tiếng Việt tự nhiên cho AI Agent:

### Kịch bản 1: Tự động làm Voiceover cho Video ngắn
> **Prompt bạn gửi cho Agent**:  
> *"Hãy viết cho tôi một kịch bản video TikTok 30 giây giới thiệu về mẹo học tiếng Anh mỗi ngày. Sau đó dùng BVoiz công cụ bvoiz_synthesize_speech với giọng nữ trẻ trung miền Bắc, đọc kịch bản đó và lưu file vào `E:/projects/tiktok/audio.mp3`."*

### Kịch bản 2: Tối ưu văn bản và thử giọng miễn phí
> **Prompt bạn gửi cho Agent**:  
> *"Tôi có đoạn văn này: 'Hôm nay lúc 8h30 tại TP.HCM đã diễn ra hội nghị AI 2026 với 500 DN tham dự'. Hãy tối ưu lại cho tự nhiên bằng prompt bvoiz_script_polisher, sau đó gọi bvoiz_demo_synthesize đọc thử cho tôi nghe."*

### Kịch bản 3: Nhân bản giọng nói và kiểm tra
> **Prompt bạn gửi cho Agent**:  
> *"Tôi có file ghi âm mẫu ở `E:/recordings/my_voice.wav`. Hãy nhân bản giọng nói với tên 'Giong_Admin' qua BVoiz, rồi đọc thử câu: 'Hệ thống đã sao lưu dữ liệu thành công'."*

### Kịch bản 4: Trợ lý tổng đài tự động hóa (Call Center IVR)
> **Prompt bạn gửi cho Agent**:  
> *"Hãy tạo 3 file audio thông báo cho tổng đài cty: 1) Lời chào, 2) Bấm phím 1 gặp CSKH, 3) Ngoài giờ làm việc. Dùng giọng Hoài My và lưu vào thư mục `./ivr_audio/`."*

---

## ❓ Xử lý sự cố thường gặp (FAQ & Troubleshooting)

#### 1. Lỗi `Cannot find module .../dist/index.js`
- **Nguyên nhân**: Bạn chưa biên dịch mã nguồn TypeScript.
- **Khắc phục**: Chạy lệnh `npm run build` trong thư mục `bvoiz-mcp`.

#### 2. Lỗi `Authorization header is required` hoặc `Token is invalid`
- **Nguyên nhân**: Biến môi trường `BVOIZ_API_KEY` chưa được khai báo hoặc key đã hết hạn/bị thu hồi.
- **Khắc phục**: 
  - Truy cập [https://bvoiz.com/account](https://bvoiz.com/account) để tạo lại key mới.
  - Kiểm tra xem file cấu hình MCP của bạn đã có mục `"env": { "BVOIZ_API_KEY": "bv_live_..." }` chưa.
  - Hoặc sử dụng công cụ `bvoiz_demo_synthesize` không yêu cầu API key.

#### 3. Không lưu được file qua tham số `save_to_file`
- **Nguyên nhân**: Đường dẫn thư mục không có quyền ghi hoặc sai định dạng đường dẫn.
- **Khắc phục**: BVoiz MCP Server tự động tạo thư mục cha (`recursive: true`). Trên Windows, hãy đảm bảo đường dẫn sử dụng dấu gạch xuôi `/` hoặc dấu escape kép `\\` (ví dụ: `E:/audio/out.mp3` hoặc `E:\\audio\\out.mp3`).

#### 4. Ký tự tối đa cho mỗi lần đọc
- Gói Free/Demo: Tối đa 300 ký tự / lần.
- Gói trả phí (Basic, Advanced, Premium): Từ 25.000 đến 50.000 ký tự / lần chuyển đổi. Nếu văn bản quá dài, bật tham số `async: true` để hệ thống xử lý qua hàng đợi mà không bị timeout.

---

## 📄 Hỗ trợ & Bản quyền

- 🌐 **Trang chủ BVoiz**: [https://bvoiz.com](https://bvoiz.com)
- 📖 **Tài liệu API BVoiz**: [https://help.bvoiz.com](https://help.bvoiz.com)
- 💬 **Kênh hỗ trợ Telegram**: [https://t.me/BvoizCom](https://t.me/BvoizCom)
- 📜 **Giấy phép**: Phát hành theo giấy phép mã nguồn mở [MIT License](LICENSE).