Bắt đầu nhanh & Xác thực API

2. Hướng dẫn lấy khóa API Key

Để gửi yêu cầu tới Bvoiz API, bạn cần sở hữu một khóa API Key hợp lệ gắn liền với tài khoản của bạn. Các bước tạo khóa như sau:

3. Cơ chế xác thực Bearer Token

Bvoiz sử dụng cơ chế xác thực tiêu chuẩn HTTP Bearer Token. Trong mọi yêu cầu HTTP gửi lên hệ thống, bạn cần đính kèm header sau:

4. Gửi yêu cầu API đầu tiên

Dưới đây là ví dụ hoàn chỉnh thực hiện lệnh gọi POST /api/v1/tts để chuyển một câu văn bản thành file âm thanh MP3 bằng cURL, Python và Node.js:

curl -X POST "https://bvoiz.com/api/v1/tts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_text": "Xin chào! Đây là yêu cầu API đầu tiên của bạn trên nền tảng Bvoiz AI Voice.",
    "speaker_id": "vi_male_leduc_mb",
    "speed": 1.0,
    "pitch": 1.0,
    "volume": 100,
    "audio_type": "mp3"
  }'

5. Cấu trúc phản hồi chuẩn (Response Format)

Mọi API của Bvoiz đều tuân thủ cấu trúc phong bì (Envelope Pattern) đồng nhất. Phản hồi thành công sẽ luôn có trường "status": 1 và chứa dữ liệu trong đối tượng result:

{
  "status": 1,
  "result": {
    "request_id": "req_1790355651_a5a901a8",
    "audio_url": "https://bvoiz.com/storage/audio/req_1790355651_a5a901a8.mp3",
    "speaker_id": "vi_male_leduc_mb",
    "speaker_name": "Lê Đức (Nam - Bắc)",
    "provider": "bvoiz",
    "char_count": 82,
    "duration_sec": 4.65,
    "file_size": 74320,
    "expires_at": "2026-10-28T12:00:00Z"
  }
}

Nếu có lỗi xảy ra (do thiếu tham số, token sai, hoặc tài khoản hết hạn mức), API sẽ trả về mã lỗi HTTP tương ứng kèm "status": 0 và thông điệp hướng dẫn cụ thể:

{
  "status": 0,
  "code": "INVALID_API_KEY",
  "message": "Khóa API không hợp lệ hoặc đã bị vô hiệu hóa.",
  "errors": null
}

6. Bảng mã trạng thái HTTP chuẩn