Chuyển tới nội dung chính

Vapi (agent thoại)

Vapi dựng các agent thoại biết nghe máy và gọi đi. Nó phát tiếng qua một nhà cung cấp TTS do bạn chọn — và provider custom-voice cho phép nhà cung cấp đó là bất kỳ endpoint HTTPS nào. VieNeu hiện thực đúng những gì Vapi mong đợi, nên agent của bạn có thể trả lời bằng tiếng Việt.

Điều này quan trọng vì tiếng Việt gần như vắng bóng trong các nhà cung cấp TTS realtime mà Vapi có sẵn.

Cấu hình assistant​

{
  "voice": {
    "provider": "custom-voice",
    "server": {
      "url": "https://api.vieneu.io/api/v1/vapi/speech?voiceId=Ngọc%20Lan",
      "secret": "vn_sk_your_key_here",
      "timeoutSeconds": 30
    }
  }
}

Tích hợp chỉ có vậy. Hai chi tiết gánh toàn bộ phần việc:

secret chính là API key VieNeu của bạn. Vapi gửi nó trong header X-VAPI-SECRET, còn cấu hình của Vapi không có trường nào cho header Authorization — nên key phải đặt ở đây. Vẫn là key đó, vẫn được kiểm tra theo cách đó, và vẫn tính tiền vào cùng một tài khoản.

Giọng đọc nằm trong URL. Payload request của Vapi không có trường nào cho giọng, nên hãy truyền ?voiceId= (đã URL-encode). Xem danh sách lựa chọn bằng GET /v1/audio/voices. Thêm &engine=v4 để dùng engine cao cấp nếu gói của bạn có. Bỏ hẳn voiceId thì bạn nhận giọng mặc định của engine.

Điều gì diễn ra ở mỗi lượt nói​

Vapi gửi POST:

{
  "message": {
    "type": "voice-request",
    "text": "Xin chào, tôi có thể giúp gì cho bạn?",
    "sampleRate": 24000
  }
}

VieNeu trả về 200 với Content-Type: application/octet-stream cùng dữ liệu PCM thô, mono, 16-bit little-endian, đúng sample rate đó, được stream ngay trong lúc sinh chứ không đệm lại — nhờ vậy agent bắt đầu nói sớm hơn.

Tuỳ transport, Vapi sẽ yêu cầu 8000, 16000, 22050 hoặc 24000 Hz. Cả bốn đều được hỗ trợ, và phản hồi luôn ở đúng sample rate được yêu cầu: PCM thô không tự mang thông tin sample rate, nên trả về khác đi là âm thanh sẽ sai cao độ.

Tính phí và hành vi​

Tính phí theo số ký tự gửi lên, như phần còn lại của /v1. Audio bị cắt ngang sẽ được hoàn tiền tự động.

Tinh chỉnh bằng AI không bao giờ chạy trên endpoint này, bất kể cài đặt tài khoản của bạn là gì. Việc của một agent là trả lời nhanh, mà thêm một vòng gọi model trước mỗi lượt nói thì đi ngược lại điều đó. Bước chuẩn bị văn bản tất định vẫn chạy, nên tiếng Việt vẫn được phát âm đúng. Nếu văn bản của agent có những thứ bạn muốn đọc theo một cách nhất định — tiền tệ, ngày tháng, mã sản phẩm — hãy chuẩn hoá chúng ngay trong prompt, nơi bạn nhìn thấy được kết quả.

Nói thật về độ trễ​

Với các gói thường, gói âm thanh đầu tiên rời server sau khoảng 1–2 giây. Chừng đó đủ cho một agent trả lời một câu hỏi, đọc một thực đơn, xác nhận một lượt đặt chỗ. Nó chậm hơn mức 200–300 ms mà những nhà cung cấp nhanh nhất trong nhóm chỉ hỗ trợ tiếng Anh đạt được, và người nghe sẽ nhận ra một nhịp chờ trước khi agent cất tiếng.

Hợp đồng Enterprise chạy trên node riêng, trần độ trễ do hai bên thoả thuận — xuống tới ≤ 250 ms — và đó là phiên bản bạn cần nếu nhịp chờ ấy là thứ không chấp nhận được. Xem Nói thật về độ trễ.

Hai việc đáng làm: giữ timeoutSeconds ở 30 trở lên, và giữ mỗi lượt nói ngắn gọn — một đoạn văn bắt người ta chờ lâu hơn ba câu.

Mỗi lượt nói bị giới hạn 800 ký tự (khoảng 50 giây âm thanh), và giới hạn này tồn tại đúng vì lý do đó: một lượt dài hơn không thể trả kịp trong hạn 30 giây của Vapi, nên nó sẽ bị cắt ngang giữa từ mà vẫn bị tính tiền. Nếu agent của bạn sinh ra câu trả lời dài hơn, hãy tách nhỏ — Vapi sẽ yêu cầu từng mảnh riêng và người gọi nghe chúng nối liền nhau.

Nếu sau 12 giây vẫn chưa worker nào bắt đầu trả lời, request sẽ trả về 503 thay vì giữ socket cho tới khi Vapi bỏ cuộc. Khác biệt đó có ý nghĩa: một mã trạng thái mà fallbackPlan của bạn xử lý được thì hơn hẳn một cú timeout, vốn chỉ trông như một nhà cung cấp đã ngừng phản hồi.

Hãy đặt fallbackPlan cho assistant nếu việc hụt một lượt nói còn tệ hơn việc dùng một giọng không phải tiếng Việt.

Xử lý sự cố​

Triệu chứngNguyên nhân
401secret không phải API key VieNeu hợp lệ, hoặc key đã bị thu hồi.
400 kèm thông báo về giọngvoiceId không có trong danh mục của engine đó — hãy kiểm tra GET /v1/audio/voices.
403Token grant của key đã cạn hoặc hết hạn, hoặc gói của bạn không bao gồm engine đó.
400 về độ dài message.textLượt nói dài quá 800 ký tự — hãy tách nhỏ.
503 có nêu một sample rateChưa worker nào trong pool được cập nhật để xuất PCM thô. Chúng tôi failover khắp cụm trước đã, nên lỗi này nghĩa là tất cả đều chưa. Hãy thử lại; liên hệ chúng tôi nếu vẫn còn.
503 báo không worker nào trả lờiKhông có gì bắt đầu tạo audio trong vòng 12 giây. Thường là do đột biến tải; fallbackPlan của bạn đỡ lượt nói đó.
502 báo không có audioWorker đã nhận request rồi không sinh ra gì cả. Không bị tính phí.

Mọi phản hồi đều mang X-Request-Id. Gửi kèm mã đó, chúng tôi tìm được đúng lệnh gọi ấy.