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

Bắt đầu nhanh

Ba bước, và bước thứ ba trả về audio. Không bước nào cần đến SDK.

1. Lấy API key​

Key nằm ở trang Developer trong web app VieNeu. Tạo một key, sao chép ngay lần đầu — chuỗi gốc chỉ hiện đúng lúc tạo và không bao giờ hiện lại — rồi đặt nó vào biến môi trường:

export VIENEU_API_KEY="vn_sk_..."

Key chỉ được cấp khi tài khoản đang có một token grant còn hiệu lực, nên tài khoản mới tinh phải kích hoạt một grant trước; trang Developer có bản dùng thử miễn phí 7 ngày làm đúng việc đó, mỗi tài khoản một lần. Không có grant, lệnh tạo key trả về 403 kèm No active API token grant found.

Key bắt đầu bằng vn_sk_ là key thật. Key vn_test_ hoạt động y hệt — cùng cách tính phí, cùng giới hạn, cùng endpoint — chỉ khác là mỗi request bị giới hạn 100 từ, nên bạn có thể yên tâm dán chúng vào repo mẫu.

2. Chọn giọng​

Danh mục giọng là công khai — lời gọi này không cần key:

curl -s "https://api.vieneu.io/api/v1/voices?engine=v4" | head -c 400
{"voices":[{"id":"Ngọc Lan","description":"Giọng nữ, giọng trầm dịu dàng",
  "name":"Ngọc Lan","gender":"female","region":"south","engine":"v4",
  "kind":"catalog"}, …]}

Trường id là thứ bạn gửi đi. Luôn lọc theo engine. Mỗi giọng chỉ thuộc về một engine, hai danh mục chỉ thay cho nhau được một phần, và gửi id của engine kia sẽ nhận 400 chứ không được thay bằng giọng khác — xem voice id khác nhau theo engine.

3. Tổng hợp giọng nói​

POST /v1/audio/speech trả thẳng các byte audio ngay trong response — không job, không polling. Đây chính là dạng endpoint của OpenAI, nên client OpenAI dùng được ngay mà không phải sửa gì; xem endpoint tương thích OpenAI.

curl​

curl 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.", "voice": "Ngọc Lan" }' \
  --output speech.mp3

Python​

# pip install requests
import os
import requests

resp = requests.post(
    "https://api.vieneu.io/api/v1/audio/speech",
    headers={"Authorization": f"Bearer {os.environ['VIENEU_API_KEY']}"},
    json={"input": "Xin chào, đây là VieNeu.", "voice": "Ngọc Lan"},
    timeout=120,
)
resp.raise_for_status()
with open("speech.mp3", "wb") as f:
    f.write(resp.content)
print("wrote speech.mp3", len(resp.content), "bytes")

JavaScript​

// Node 18+ — no dependencies.
import { writeFile } from 'node:fs/promises';

const resp = await fetch('https://api.vieneu.io/api/v1/audio/speech', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VIENEU_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ input: 'Xin chào, đây là VieNeu.', voice: 'Ngọc Lan' }),
});
if (!resp.ok) throw new Error(`HTTP ${resp.status}: ${await resp.text()}`);

await writeFile('speech.mp3', Buffer.from(await resp.arrayBuffer()));
console.log('wrote speech.mp3');

Vậy là bạn đã có một tệp mp3. Muốn định dạng khác thì đổi response_format — wav, opus, pcm và ulaw 8 kHz đều dùng được, chi tiết từng trường nằm trong tài liệu API, ở mục createSpeech.

Đi tiếp từ đây​

  • Văn bản dài — /v1/audio/speech giữ kết nối mở suốt quá trình tổng hợp. Dài hơn vài đoạn văn thì hãy gửi một job thay vì gọi trực tiếp: xem hai cách tổng hợp.
  • Phát audio trước khi tổng hợp xong văn bản — Streaming.
  • Khi request lỗi — Lỗi liệt kê mọi code máy đọc được và cách xử lý từng loại.
  • Mọi thứ còn lại — tài liệu API được sinh ra từ chính định nghĩa route của server và bao quát mọi trường của mọi endpoint.