Skip to main content

Changelog

Thay đổi của Cloud API (/api/v1). Mục nào đánh dấu ⚠️ Thay đổi hành vi là thứ có thể ảnh hưởng đến tích hợp đang chạy của bạn kể cả khi bạn không sửa gì.

2026-08 — Định dạng đầu ra, tương thích OpenAI, và Vapi​

Mới​

Giọng nhân bản chạy được trên POST /v1/tts/stream. Truyền id clone_… (lấy từ GET /v1/voices, tạo bằng POST /v1/voices) vào voiceId là stream được, y như một giọng có sẵn. Trước đây đường stream từ chối mọi id clone_… trong khi ứng dụng web đã phát trực tiếp giọng nhân bản từ lâu — worker vốn hỗ trợ, chỉ có bề mặt công khai là chặn.

  • Tính tiền không đổi: vẫn theo số ký tự gửi lên × hệ số của engine. Nhân bản không có phụ phí riêng; khoản duy nhất là phí ghi danh một lần ở POST /v1/voices.
  • Giọng nhân bản gắn với đúng engine lúc ghi danh, nên quy tắc "stream chỉ chạy v4" vẫn áp dụng. Clone mới đều ghi danh v4.
  • Không phải là thay đổi hành vi: những gì chạy được hôm qua vẫn chạy y hệt.

Nhiều định dạng đầu ra. POST /v1/tts/stream và POST /v1/audio/speech giờ nhận mp3, opus, pcm (thô, không header) và ulaw (G.711 8 kHz cho tổng đài), kèm chọn sample rate. Trước đây chỉ có WAV 48 kHz. mp3 nhỏ hơn WAV khoảng 6 lần.

POST /v1/audio/speech là bản drop-in thật sự cho OpenAI. Trỏ SDK OpenAI vào https://api.vieneu.io/api/v1 với API key của bạn là chạy, không sửa gì thêm. speed đã được áp dụng, model chọn engine, và stream_format cho phép nhận audio ngay trong lúc đang tạo (chunked hoặc SSE kiểu OpenAI). Thêm GET /v1/audio/voices để các client OpenAI lấy danh sách giọng.

POST /v1/vapi/speech — webhook custom-voice cho Vapi. Trỏ custom-voice của assistant vào URL này là agent thoại của bạn nói tiếng Việt. Chi tiết trong Tích hợp Vapi.

Header hạn mức trên mọi phản hồi. X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, và X-Request-Id — hãy trích X-Request-Id khi liên hệ hỗ trợ, đó là mã log của chúng tôi.

Tài liệu công khai. Mục Cloud API trên docs.vieneu.io, kèm decoder tham chiếu Python và JavaScript cho streaming.

⚠️ Thay đổi hành vi​

aiRefine mặc định chuyển từ BẬT sang TẮT. Bước tinh chỉnh bằng AI (kiểm duyệt nội dung + chuẩn hoá phát âm cho công thức, từ viết tắt, tiếng Anh xen kẽ) trước đây chạy mặc định trên /v1 và tính thêm phụ phí. Giờ bạn phải chủ động bật bằng "aiRefine": true.

  • Bạn sẽ thấy gì: chi phí mỗi request giảm, độ trễ giảm, và văn bản được đọc đúng như bạn gửi.
  • Nếu bạn muốn giữ hành vi cũ: thêm "aiRefine": true vào request. Với POST /v1/srt (multipart) là trường aiRefine=true.
  • Chuẩn hoá văn bản tất định (cách đọc hoá học, gộp CHỮ HOA, tầng phiên âm sea-g2p) vẫn chạy trong mọi trường hợp — tiếng Việt vẫn đọc đúng.

Mặc định của response_format trên /v1/audio/speech chuyển từ wav sang mp3. Đây là mặc định của OpenAI, và một client OpenAI bỏ trống trường này là đang mong đợi mp3. Nếu bạn cần WAV, gửi "response_format": "wav".

Hạn mức đổi đơn vị: từ mỗi IP sang mỗi API key. Trước đây đếm theo địa chỉ IP, nghĩa là một văn phòng dùng chung mạng phải chia nhau hạn mức, còn một key chạy trên nhiều máy thì được nhân lên. Giờ đếm theo key — đúng thứ bạn mua. Đi kèm, trần của ba route tổng hợp chính đã được nâng lên 300 request/phút để không ai bị hụt so với trước.

Sửa lỗi​

  • Streaming qua api.vieneu.io không còn bị proxy gom lại — audio đến ngay khi được tạo, đúng như thiết kế.
  • POST /v1/tts/stream giờ báo đúng định dạng và sample rate thật trong header X-Output-Format / X-Sample-Rate, thay vì lặp lại thứ bạn yêu cầu.
  • Stream bị cắt giữa chừng được hoàn tiền đáng tin cậy hơn: một stream kết thúc đúng quy cách nhưng không mang audio nào giờ cũng được hoàn.

Giới hạn đã biết​

stream_format (và streaming nói chung) chỉ nên dùng với pcm và ulaw. Các khung audio được mã hoá độc lập nhau, nên nối mp3 lại sẽ có khoảng lặng ở mỗi mối nối, còn opus thành chuỗi Ogg mà phần lớn trình duyệt chỉ phát đoạn đầu. Cần một file mp3 hoặc opus hoàn chỉnh thì gửi request thường, không streaming.