- SDK chính thức: @vovix/voixa (Node, Bun, Deno, Cloudflare Workers), voixa (Python 3.9+) và Go.
- say() chờ tới khi audio xong và trả URL WAV dùng được trong một giờ.
- Hết token thì API trả lỗi 402 INSUFFICIENT_TOKENS; clip hỏng được hoàn token.
- Clip tạo qua API tự xoá sau 24 giờ, hãy tải file về lưu phía bạn.
Voixa có API REST và SDK chính thức cho TypeScript/JavaScript, Python và Go. Bài này đi từ con số không tới file WAV đầu tiên, rồi chỉ cách làm vài việc thường gặp. Bạn cần Node.js 18 trở lên hoặc Python 3.9 trở lên.
Bắt đầu
Tạo khoá API
Đăng nhập Voixa, mở Khoá API ở thanh bên và tạo khoá mới. Khoá đầy đủ chỉ hiện một lần: chép ngay vào biến môi trường VOIXA_API_KEY trên máy chủ của bạn.
Khoá vừa tạo có thể trả lỗi Forbidden trong 2–3 phút đầu, trong lúc hệ thống cập nhật. Đợi một chút rồi thử lại.
Cài SDK
npm install @vovix/voixa # Node 18+, Bun, Deno, Cloudflare Workers
pip install voixa # Python 3.9+Đọc câu đầu tiên
Node.js:
import { writeFile } from 'node:fs/promises'
import { Voixa } from '@vovix/voixa'
const vx = new Voixa({ apiKey: process.env.VOIXA_API_KEY })
// say() chờ tới khi audio xong
const clip = await vx.say({ voiceId: 'vi-truc-ly', text: 'Xin chào, đây là giọng đọc của Voixa.' })
const wav = await fetch(clip.url).then((r) => r.arrayBuffer())
await writeFile('xin-chao.wav', Buffer.from(wav))
console.log(clip.durationSec, 'giây')Python:
import urllib.request
from voixa import Voixa
vx = Voixa() # đọc VOIXA_API_KEY từ biến môi trường
clip = vx.say(voice_id="vi-truc-ly", text="Xin chào, đây là giọng đọc của Voixa.")
urllib.request.urlretrieve(clip["url"], "xin-chao.wav")
print(clip["durationSec"], "giây")Không dùng SDK thì gọi thẳng bằng cURL:
curl -X POST https://api.voixa.vovix.io/v1/speak \
-H "x-api-key: $VOIXA_API_KEY" \
-H "content-type: application/json" \
-d '{ "voiceId": "vi-truc-ly", "text": "Xin chào, đây là Voixa." }'Chọn giọng
vx.voices({ language: 'vi' }) trả danh sách giọng bạn dùng được: giọng có sẵn, cùng giọng bạn đã clone hay thiết kế. Mỗi giọng có voiceId để truyền vào say. Trong Studio, id hiện cạnh từng giọng kèm nút sao chép.
Không muốn chờ trong request?
say() đợi tới khi audio xong. Trong một request web, bạn có thể gọi speak({ wait: false }) để nhận clip ở trạng thái đang xử lý trong chưa tới một giây, trả lời người dùng trước, rồi dùng waitFor hoặc hỏi lại clip theo id sau.
Vài việc thường gặp
Podcast từ kịch bản dài
const episode = await vx.makePodcast({ voiceId: 'vi-ngoc-linh', title: 'Bản tin sáng', text: script })Kịch bản tới 100.000 ký tự, xem thêm cách tạo podcast tiếng Việt bằng AI.
Chép lời một file
import { readFile } from 'node:fs/promises'
const t = await vx.transcribeFile({ audio: await readFile('phong-van.mp3'), fileName: 'phong-van.mp3', diarize: true })
console.log(t.text, t.srtUrl)Chi tiết các tuỳ chọn ở hướng dẫn tạo phụ đề SRT tự động.
Gom clip theo dự án
Thêm project: 'ten-du-an' vào say hoặc makePodcast: clip hiện trong dự án đó ở Studio, và lọc lại được bằng listClips({ project }).
Token và lỗi
Mọi request tính bằng token (1 token = 1 ký tự tiếng Việt); xem số dư bằng vx.account(). Khi không đủ token, SDK ném VoixaError với status 402 và code là INSUFFICIENT_TOKENS:
import { VoixaError } from '@vovix/voixa'
try {
await vx.say({ voiceId: 'vi-truc-ly', text })
} catch (e) {
if (e instanceof VoixaError && e.code === 'INSUFFICIENT_TOKENS') {
// báo người dùng nạp thêm token
} else throw e
}Clip, podcast và bản chép lời tạo bằng khoá API tự xoá sau 24 giờ. Hãy tải file về lưu phía bạn; clip nào cần giữ lâu thì tạo liên kết chia sẻ cho clip đó.
Khoá thông thường có trần 1 request mỗi giây và 1.000 request mỗi ngày. Cần nhiều hơn, hãy gửi yêu cầu trong mục Cộng đồng.
Tiếp theo
Tiếng Việt có thêm streaming: nghe được những chữ đầu tiên sau khoảng hai giây, hợp cho tổng đài và trợ lý giọng nói. Tài liệu API có mọi route với ví dụ cURL, TypeScript, Python và Go, gồm cả streaming.
Câu hỏi thường gặp
Gọi API từ trình duyệt được không?
SDK chạy được trên trình duyệt, nhưng đừng đặt khoá API trong code phía trình duyệt vì ai cũng đọc được. Hãy gọi từ máy chủ của bạn rồi trả URL audio cho trình duyệt.
URL audio dùng được bao lâu?
URL WAV là link ký sẵn, dùng được một giờ. Cần lâu hơn thì tải file về lưu, hoặc lấy lại clip theo id để nhận link mới khi clip còn tồn tại.
Có webhook báo khi việc dài xong không?
Chưa. Với podcast và chép lời, dùng các hàm chờ của SDK như makePodcast, transcribeFile, waitFor, hoặc tự hỏi lại theo id.
Có SDK cho Go không?
Có, gói github.com/vovix-ai/voixa-go, chỉ dùng thư viện chuẩn. Tài liệu ở mục SDKs trong tài liệu API.
Bình luận
Email không hiển thị công khai.
Chưa có bình luận nào. Hãy là người đầu tiên.