# Tổng quan tích hợp

Source: https://docs.vieneu.io/vi/docs/integrations/overview

:::info 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](../cloud-api/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 {#which-path-is-yours}

| 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 OpenAI | Ba ô cài đặt: base URL, key, voice id. Không plugin, không adapter. | [App tương thích OpenAI](./openai-clients.md) — cách cài theo từng client và gỡ rối theo triệu chứng · [tham chiếu endpoint](../cloud-api/openai-compatible) |
| Một **trợ lý AI** — Claude, ChatGPT, Cursor, Claude Code | MCP 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](./mcp/index.md) |
| **n8n** | Mộ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](./n8n.md) |
| Một **voice agent hoặc hệ thống điện thoại** | Vapi 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](../cloud-api/vapi) · [LiveKit / Pipecat](./openai-clients.md#livekit-agents) · [Streaming](../cloud-api/streaming) |
| **Code của chính bạn** | Gọ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](../cloud-api/overview) · [API reference](/api-reference) |
| Một thứ cần **phản ứng khi job chạy xong** | Đăng ký một webhook thay vì poll. | [Webhooks](../cloud-api/webhooks) |

## Điểm chung của mọi đường {#what-every-path-shares}

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](../cloud-api/overview#authentication).

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í](../cloud-api/overview#billing).

## Trọn một request từ đầu tới cuối {#one-request-end-to-end}

```bash
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](../cloud-api/overview#engines) — 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 đó:

```bash
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](./openai-clients.md#getting-voice-ids).

## Những gì hình dạng OpenAI không với tới {#what-the-openai-shape-cannot-reach}

`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](../cloud-api/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](https://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](./openai-clients.md).

## Nói thật về độ trễ {#latency-honestly}

**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ễ](../cloud-api/streaming#latency-honestly).