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

Tổng quan tích hợp

n8n node chưa được phát hành

n8n node (n8n-nodes-vieneu 0.1.0) đang để private và chưa từng được publish lên npm. Node đã dựng xong và chạy được, nhưng repository chứa nó không công khai, nên hôm nay chưa có lệnh cài nào bạn chạy được — hãy liên hệ VieNeu để lấy package, và theo dõi changelog để biết lúc phát hành.

Không có thứ nào khác ở đây phụ thuộc vào nó. MCP server, endpoint tương thích OpenAI, API gốc, webhook và Vapi đều đang chạy và không cần cài gì cả.

Trang này dẫn bạn tới đúng lối cho mình. Mỗi đích đến tự giữ phần chi tiết của nó; trang này cố ý không nhắc lại gì.

Đường nào là của bạn​

Bạn đã có sẵn gìVieNeu ghép vào kiểu nàoỞ đâu
Một app nói được giao thức TTS của OpenAI — Open WebUI, SillyTavern, LobeChat, LiteLLM, bất cứ thứ gì chạy trên SDK OpenAIBa ô cài đặt: base URL, key, voice id. Không plugin, không adapter.App tương thích OpenAI — cách cài theo từng client và gỡ rối theo triệu chứng · tham chiếu endpoint
Một trợ lý AI — Claude, ChatGPT, Cursor, Claude CodeMCP server chạy sẵn trên máy chủ VieNeu: thêm https://api.vieneu.io/mcp, đăng nhập tài khoản VieNeu, rồi nhờ đọc tiếng Việt bằng lời thường. Không cần cài gì.MCP server
n8nMột community node (n8n tự host, build từ source), hoặc hai workflow dựng sẵn từ chính node HTTP Request của n8n — không cài gì và chạy được trên n8n Cloud.n8n node
Một voice agent hoặc hệ thống điện thoạiVapi có một route webhook riêng. LiveKit Agents, Pipecat và mọi thứ khác có plugin TTS OpenAI thì dùng /v1/audio/speech với response_format: "pcm".Vapi · LiveKit / Pipecat · Streaming
Code của chính bạnGọi thẳng /api/v1 — bề mặt đó lớn hơn nhiều so với phần mang hình dạng OpenAI.Tổng quan Cloud API · API reference
Một thứ cần phản ứng khi job chạy xongĐăng ký một webhook thay vì poll.Webhooks

Điểm chung của mọi đường​

Base URL https://api.vieneu.io/api/v1. Một key, đặt dưới tên header nào cũng được:

Authorization: Bearer vn_sk_...
X-API-Key: vn_sk_...

Key vn_sk_ là key thật; key vn_test_ hoạt động y hệt nhưng chặn mỗi request ở 100 từ. Mọi chuỗi khác — sk-…, none, một chỗ điền để trống — đều là 401 trước cả khi có bất kỳ lần tra cứu nào, nên client nào bắt buộc phải có một ô key không rỗng thì phải đưa nó key thật. Một token Bearer chứa dấu chấm bị đọc thành JWT rồi bỏ qua, và đó là lý do dán một cái vào cho ra "API key required" chứ không phải "invalid key". Còn một header thứ ba, X-VAPI-SECRET, được nhận trên mọi route /v1 — đứng cuối trong thứ tự ưu tiên, nên một header nêu thẳng bao giờ cũng thắng. Nó tồn tại vì cấu hình của một assistant Vapi không đặt được header nào trong hai header kia. Xem Xác thực.

Việc tổng hợp giọng nói tính phí theo ký tự gửi lên, tối thiểu 50, nhân với hệ số của engine; request không tạo ra được audio sẽ được hoàn tiền tự động. Xem Tính phí.

Trọn một request từ đầu tới cuối​

curl -sS https://api.vieneu.io/api/v1/audio/speech \
  -H "Authorization: Bearer $VIENEU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "Xin chào, đây là VieNeu.", "response_format": "mp3"}' \
  --output speech.mp3

Hãy nêu tên response_format dù mp3 vốn đã là mặc định. Chỉ một yêu cầu mp3 nói thẳng ra mới chắc chắn nhận về mp3: khi request không hề nhắc tới định dạng và worker không mã hoá được mp3, endpoint lùi về wav thay vì báo lỗi, còn -sS --output thì vứt luôn header X-Output-Format — cái đáng lẽ đã báo cho bạn biết. Ghi vào speech.mp3, đó là chuỗi byte mà trình phát của bạn từ chối.

Bỏ trống voice thì dùng giọng đang hoạt động đầu tiên trên engine mặc định đã cấu hình (xem Engine — engine cũng chính là thứ đặt hệ số giá). Muốn tự chọn, hãy hỏi xem engine nào đang là mặc định, rồi liệt kê giọng của đúng engine đó:

curl -sS https://api.vieneu.io/api/v1/engines      # no key needed; find "isDefault": true
curl -sS "https://api.vieneu.io/api/v1/audio/voices?engine=<that key>" \
  -H "Authorization: Bearer $VIENEU_API_KEY"

v4 là mặc định của hôm nay — và từ khi v3 rút khỏi Cloud API ngày 2026-09-24, cũng là engine duy nhất — nhưng registry mới là nguồn sự thật, hãy thay bằng đúng thứ lời gọi đầu tiên báo về. Id của danh mục đã ngừng (slug vieneu-… khó đọc) gần như không chung không gian với tên hiển thị của v4, nên một giọng lưu từ danh sách chưa lọc trước ngày ngừng giờ trả 400; hãy chọn một id mới. Chi tiết ở Lấy voice id.

Những gì hình dạng OpenAI không với tới​

POST /api/v1/audio/speech, cộng thêm GET /api/v1/audio/voices đi kèm mà ô chọn giọng của nó đọc, là trọn bề mặt tương thích — không có adapter nào phải cài và không có gì phải bảo trì riêng cho từng client. Hai thứ nằm ngoài hình dạng đó, và nếu bạn đang so sánh các nhà cung cấp thì nên thử thẳng chúng thay vì suy đoán:

  • Streaming tăng dần. POST /v1/tts/stream, và stream_format trên route OpenAI, giao audio ngay khi nó được sinh ra, chứ không phải một lượt tải về đã đệm sẵn mang cái nhãn streaming. Khả năng này khai báo theo từng engine — features trên GET /v1/engines có stream cho v4; engine v3 đã ngừng ngày 2026-09-24 chưa bao giờ có nó, vì nó dồn hết các chunk ra một lượt ở cuối và không giữ nổi lời hứa độ trễ. Xem Streaming.
  • Giọng nhân bản, gọi được từ code. Bạn nhân bản giọng một lần trên Studio web (vieneu.io/#/clone) — đường có người dẫn: khử nhiễu clip, tự chép lời và cho nghe thử trước khi lưu — rồi id clone_… của nó chạy trên POST /v1/tts và POST /v1/tts/stream như mọi giọng catalogue. Đây là thứ duy nhất mà một client tương thích OpenAI không với tới được: một id clone_… trên /v1/audio/speech là 400.

Những chỗ vướng nhỏ hơn của hình dạng OpenAI — không có GET /v1/models, field lạ trong body bị từ chối chứ không bị bỏ qua, tên giọng của OpenAI không được ánh xạ, cái bẫy base URL nhân đôi /api/v1, streaming cần tới hai field, CORS phía trình duyệt, và lỗi 429 nào đến từ đâu — tất cả đều có một triệu chứng và một cách chữa ở App tương thích OpenAI.

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

Với các gói thường, audio đầu tiên về trong khoảng 1–2 giây. Mức đó thoải mái cho đọc thành tiếng, câu thoại IVR, lồng tiếng và những trợ lý chịu được một nhịp lặng trước khi cất tiếng. Nó không thuộc hạng 200–300 ms mà các conversational agent thời gian thực nghiêm ngặt trông đợi. Enterprise thì chạy trên node riêng, trần đó do hai bên thoả thuận — xuống tới ≤ 250 ms. Dù thế nào, hãy thiết kế quanh con số bạn tự đo được trên đúng gói mình đang dùng — xem Nói thật về độ trễ.