API giọng nói 88API: TTS và STT
Tài liệu tích hợp mô hình giọng nói Grok và Gemini: tổng hợp giọng nói qua /v1/audio/speech, tổng hợp giọng nói streaming qua WebSocket, hội thoại giọng nói thời gian thực Grok, chuyển ghi qua /v1/audio/transcriptions và qua hội thoại có âm thanh; gồm toàn bộ giọng đọc, định dạng đầu ra, trường yêu cầu, ví dụ cURL, OpenAI SDK, Python và Node.js.
88API cung cấp hai nhóm mô hình giọng nói Grok và Gemini. Tổng hợp giọng nói (TTS) và chuyển giọng nói thành văn bản (STT) dùng mô hình, endpoint và trường khác nhau; hãy chọn theo bảng dưới đây.
Mô hình và endpoint
| Năng lực | Mô hình | Endpoint | Tính phí theo |
|---|---|---|---|
| Tổng hợp giọng nói | grok-tts | POST /v1/audio/speech | Số ký tự đầu vào |
| Tổng hợp giọng nói streaming | grok-tts | WebSocket /v1/tts | Số ký tự đầu vào |
| Hội thoại giọng nói thời gian thực | grok-voice-latest, grok-voice-3.0 | WebSocket /v1/realtime | Thời lượng cuộc gọi |
| Tổng hợp giọng nói | gemini-3.8-flash-tts | generateContent gốc của Gemini (trả về liên kết tải âm thanh) | Token |
| Chuyển giọng nói thành văn bản | grok-stt | POST /v1/audio/transcriptions | Thời lượng âm thanh |
| Chuyển giọng nói thành văn bản | gemini-3-stt, gemini-3.5-stt, gemini-3.5-transcribe | POST /v1/audio/transcriptions, POST /v1/chat/completions (đầu vào âm thanh), hoặc generateContent gốc của Gemini | Token |
- Giá lấy theo hiển thị tại Thị trường mô hình trong bảng điều khiển. Nhóm của token chọn
语音模型(tên nhóm hiển thị trong bảng điều khiển) hoặc nhóm tự động. - Mô hình giọng nói chỉ dùng được với các endpoint trong bảng trên. Gọi mô hình TTS hoặc
grok-sttqua endpoint hội thoại, Responses hoặc Messages sẽ trả về400, kèm gợi ý chuyển sang endpoint đúng. - Không cung cấp endpoint
/v1/audio/translations(dịch âm thanh sang tiếng Anh). /v1/audio/speechtrả về toàn bộ âm thanh trong một lần, không hỗ trợ streaming; truyềnstream_format: "sse"sẽ trả về400. Khi cần vừa tổng hợp vừa phát, hãy dùng tổng hợp giọng nói streaming Grok.
Địa chỉ gốc và xác thực:
Base URL: https://api.88api.ai/v1
Authorization: Bearer $API_KEYTổng hợp giọng nói Grok (grok-tts)
cURL
curl --fail-with-body https://api.88api.ai/v1/audio/speech \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-tts",
"input": "Chào mừng bạn đến với dịch vụ tổng hợp giọng nói 88API.",
"voice": "eve",
"language": "vi",
"response_format": "mp3"
}' \
--output speech.mp3Phản hồi thành công là dữ liệu âm thanh nhị phân, không phải JSON; hãy ghi trực tiếp vào tệp. Trên Windows, truyền văn bản không phải ASCII bằng -d dễ bị lỗi mã hóa ký tự; có thể lưu thân yêu cầu thành tệp UTF-8 rồi gửi bằng --data-binary @request.json.
Trường yêu cầu
| Trường | Kiểu | Bắt buộc | Mặc định | Mô tả |
|---|---|---|---|---|
model | string | Có | — | grok-tts |
input | string | Có | — | Văn bản cần đọc, không được rỗng; có thể chèn các thẻ biểu cảm ở phần dưới |
voice | string | Không | eve | Xem bảng giọng đọc bên dưới, không phân biệt chữ hoa/thường. Tên giọng của OpenAI như alloy, nova sẽ trả về 400 |
response_format | string | Không | mp3 | mp3, wav, pcm, mulaw, alaw; opus, aac, flac sẽ trả về 400 |
language | string | Không | Tự động nhận dạng | Mã ngôn ngữ, như zh, en, ja, ko, fr, ru, vi, pt-BR. Cố định ngôn ngữ ổn định hơn tự động nhận dạng |
speed | number | Không | 1.0 | Hệ số tốc độ đọc, phạm vi 0.7–1.5, vượt quá trả về 400 |
sample_rate | integer | Không | 24000 | 8000, 16000, 22050, 24000, 44100, 48000; giá trị khác trả về 400 |
bit_rate | integer | Không | 128000 | Chỉ có hiệu lực với MP3: 32000, 64000, 96000, 128000, 192000 |
text_normalization | boolean | Không | false | Khi là true, chuyển số, từ viết tắt và ký hiệu thành cách đọc khẩu ngữ trước khi tổng hợp |
replace | object | Không | — | Bảng thay thế cách phát âm, ví dụ {"nginx": "engine x"}; khóa là văn bản gốc, giá trị là cách đọc |
sample_rate, bit_rate, text_normalization, replace là các trường mở rộng của Grok; trong OpenAI SDK, truyền chúng qua extra_body. Trường instructions không có tác dụng với grok-tts; hãy điều khiển giọng điệu bằng thẻ biểu cảm.
Định dạng đầu ra
response_format | Content-Type | Mô tả |
|---|---|---|
mp3 | audio/mpeg | Mặc định 24 kHz, 128 kbps, phát được ngay |
wav | audio/wav | 16-bit mono, phù hợp để biên tập hậu kỳ |
pcm | audio/pcm | PCM thô 16-bit mono, không có header, cần đọc theo tần số lấy mẫu |
mulaw | audio/basic | G.711 μ-law, cho tình huống điện thoại, thường dùng với sample_rate: 8000 |
alaw | audio/alaw | G.711 A-law, cho tình huống điện thoại, thường dùng với sample_rate: 8000 |
pcm, mulaw, alaw không phát trực tiếp được trong trình duyệt; để phát trên web, hãy dùng mp3 hoặc wav.
Giọng đọc
Mọi giọng đều đọc được tất cả các ngôn ngữ được hỗ trợ, tên không phân biệt chữ hoa/thường. Mô tả phong cách lấy từ bảng giọng đọc chính thức của xAI; nên nghe thử 2–3 giọng bằng văn bản của bạn trước khi cố định.
| Giọng đọc | Phong cách | Tình huống phù hợp |
|---|---|---|
eve | Năng động, tươi vui, giọng Anh (mặc định) | Đa dụng |
ara | Ấm áp, thân thiện | Đa dụng |
rex | Tự tin, rõ ràng | Đa dụng |
sal | Mượt mà, cân bằng | Đa dụng |
leo | Uy quyền, mạnh mẽ, giọng Anh | Đa dụng |
carina | Nhẹ nhàng, đồng cảm, êm dịu | Sức khỏe, chăm sóc khách hàng |
zagan | Mạnh mẽ, kịch tính | Nhân vật, dẫn chuyện |
helix | Táo bạo, sôi nổi | Bình luận, podcast |
orion | Trầm ấm, đậm chất điện ảnh | Dẫn chuyện, sách nói |
luna | Dịu dàng, kiên nhẫn | Giáo dục, trợ lý |
iris | Thân thiện, vui vẻ | Bán hàng, chăm sóc khách hàng |
altair | Thanh lịch, tinh tế | Quảng cáo, dẫn chuyện |
zenith | Sắc sảo, tập trung | Bán hàng, quảng cáo |
perseus | Vững vàng, đáng tin cậy | Quảng cáo, dẫn chuyện |
helios | Vui vẻ, tràn đầy năng lượng | Trợ lý, sức khỏe |
lux | Điềm tĩnh, thông thái | Sức khỏe, dẫn chuyện |
kepler | Sáng tạo, lôi cuốn | Quảng cáo, podcast |
rigel | Chính xác, chuyên nghiệp, giọng Úc | Trợ lý, chăm sóc khách hàng |
cosmo | Tươi sáng, tò mò, dễ hiểu | Giáo dục, podcast |
celeste | Chu đáo, tạo cảm giác yên tâm | Chăm sóc khách hàng, trợ lý |
ursa | Thân thiện, ấm áp, đáng tin cậy | Trợ lý, podcast |
sirius | Nhanh trí, tinh nghịch | Bình luận, nhân vật |
lumen | Ấm áp, diễn đạt rõ ràng | Giáo dục, quảng cáo |
castor | Gần gũi, thoải mái | Bán hàng, chăm sóc khách hàng |
naksh | Ấm áp, thông thái, giọng Ấn Độ | Trợ lý, chăm sóc khách hàng |
atlas | Tự tin, đầy uy lực | Bán hàng, trợ lý |
aurora | Bình thản, ổn định | Chăm sóc khách hàng, trợ lý |
liora | Ôn hòa, vững vàng | Sức khỏe, trợ lý |
Tên giọng không có trong bảng trên sẽ trả về 400, thông báo lỗi sẽ liệt kê các giọng khả dụng.
Thẻ biểu cảm
Chèn thẻ vào input để điều khiển ngắt nghỉ, tiếng cười, thì thầm và các cách biểu đạt khác; xem mô tả đầy đủ tại tài liệu chính thức của xAI.
| Loại | Thẻ |
|---|---|
| Chèn (đặt tại vị trí cần phát ra âm thanh) | [pause] [long-pause] [laugh] [chuckle] [giggle] [cry] [sigh] [breath] [inhale] [exhale] [tsk] [tongue-click] [lip-smack] [hum-tune] |
| Bao (bọc một đoạn văn bản theo cặp) | <whisper> <soft> <loud> <build-intensity> <decrease-intensity> <higher-pitch> <lower-pitch> <slow> <fast> <emphasis> <sing-song> <singing> |
{
"model": "grok-tts",
"voice": "eve",
"input": "Tôi đẩy cửa ra, [pause] và nó ở ngay đó. [laugh] <whisper>Đây là bí mật.</whisper> <slow><soft>Chúc ngủ ngon.</soft></slow>"
}Thẻ bao phải xuất hiện theo cặp và có thể lồng nhau; bọc cả câu cho hiệu quả tự nhiên hơn so với chỉ bọc một hai chữ.
Python (OpenAI SDK)
from openai import OpenAI
client = OpenAI(
api_key="YOUR_88API_KEY",
base_url="https://api.88api.ai/v1",
)
with client.audio.speech.with_streaming_response.create(
model="grok-tts",
voice="eve",
input="Chào mừng bạn đến với dịch vụ tổng hợp giọng nói 88API.",
response_format="mp3",
extra_body={"language": "vi", "sample_rate": 44100},
) as response:
response.stream_to_file("speech.mp3")Node.js (OpenAI SDK)
import fs from "node:fs";
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.API_KEY,
baseURL: "https://api.88api.ai/v1",
});
const speech = await client.audio.speech.create({
model: "grok-tts",
voice: "ara",
input: "Hello from 88API. [laugh] <whisper>This part is a secret.</whisper>",
response_format: "wav",
});
fs.writeFileSync("speech.wav", Buffer.from(await speech.arrayBuffer()));Tổng hợp giọng nói streaming Grok (WebSocket)
Phù hợp với tình huống mô hình lớn vừa sinh văn bản vừa đọc và cần bắt đầu phát càng sớm càng tốt: văn bản có thể gửi thành nhiều lần, âm thanh được trả về ngay trong lúc tổng hợp, đoạn âm thanh đầu tiên thường đến sau khoảng 0,3 giây. Mô hình, giọng đọc, thẻ biểu cảm và giá giống với grok-tts.
Kết nối
wss://api.88api.ai/v1/tts?model=grok-tts&voice=eve&codec=mp3&language=vi
Authorization: Bearer $API_KEYMọi tham số đều đặt trong chuỗi truy vấn của địa chỉ kết nối:
| Tham số | Bắt buộc | Mặc định | Mô tả |
|---|---|---|---|
model | Có | — | grok-tts |
voice | Không | eve | Xem bảng giọng đọc ở trên |
codec | Không | mp3 | mp3, wav, pcm, mulaw (cũng có thể viết ulaw), alaw; không hỗ trợ opus, aac, flac |
language | Không | Tự động nhận dạng | Mã ngôn ngữ, như zh, en, ja |
sample_rate | Không | 24000 | 8000, 16000, 22050, 24000, 44100, 48000 |
bit_rate | Không | 128000 | Chỉ có hiệu lực với MP3: 32000, 64000, 96000, 128000, 192000 |
speed | Không | 1.0 | Hệ số tốc độ đọc, phạm vi 0.7–1.5 |
text_normalization | Không | false | true hoặc false; khi là true, chuyển số, từ viết tắt và ký hiệu thành cách đọc khẩu ngữ trước khi tổng hợp |
Tin nhắn
Sau khi kết nối được thiết lập, hai bên đều gửi tin nhắn văn bản JSON:
| Chiều | Tin nhắn | Mô tả |
|---|---|---|
| Client gửi | {"type": "text.delta", "delta": "..."} | Nối thêm văn bản cần đọc, có thể gửi liên tiếp nhiều lần |
| Client gửi | {"type": "text.done"} | Đã gửi xong văn bản của đoạn này |
| Máy chủ trả về | audio.delta | delta là đoạn âm thanh mã hóa Base64; ghép theo thứ tự nhận được sẽ có âm thanh hoàn chỉnh |
| Máy chủ trả về | audio.done | Đã trả về toàn bộ âm thanh của đoạn này |
| Máy chủ trả về | error | Tổng hợp đoạn này thất bại, chi tiết trong tin nhắn |
Ví dụ phản hồi thực tế:
{"type": "audio.delta", "delta": "//PExABLjDncBN4ZECBPfcTHl40IKQ..."}
{"type": "audio.done", "trace_id": "a52a926b-726f-439c-bbeb-5d741dd497ad"}- Sau khi nhận
audio.done, kết nối vẫn được giữ; có thể tiếp tục gửitext.deltavàtext.donecủa đoạn tiếp theo mà không cần kết nối lại. - Tính phí theo số ký tự văn bản của các đoạn thực sự được tổng hợp thành âm thanh, cùng giá với
grok-tts; đoạn tổng hợp thất bại và kết nối không gửi văn bản thì không tính phí. - Chỉ hỗ trợ tin nhắn văn bản JSON, không gửi frame nhị phân.
- Tham số được kiểm tra trước khi thiết lập kết nối: khi
voicekhông có trong bảng giọng đọc (kể cả tên giọng của OpenAI), hoặc giá trị của các tham số nhưcodec,sample_rate,speedkhông hợp lệ, quá trình bắt tay sẽ trả về ngay HTTP400, không thiết lập kết nối WebSocket, và thông báo lỗi sẽ nêu các giá trị khả dụng.
Python
Cần websockets phiên bản 14 trở lên (pip install websockets).
import asyncio
import base64
import json
import websockets
API_KEY = "YOUR_88API_KEY"
URL = "wss://api.88api.ai/v1/tts?model=grok-tts&voice=eve&codec=mp3&language=vi"
async def main():
async with websockets.connect(
URL, additional_headers={"Authorization": f"Bearer {API_KEY}"}
) as ws:
segments = [
["Chào mừng bạn đến với ", "dịch vụ tổng hợp giọng nói streaming 88API, ", "văn bản vừa sinh ra vừa được đọc."],
["Cùng một kết nối có thể tiếp tục tổng hợp đoạn tiếp theo."],
]
for i, pieces in enumerate(segments):
for text in pieces:
await ws.send(json.dumps({"type": "text.delta", "delta": text}))
await ws.send(json.dumps({"type": "text.done"}))
with open(f"part{i + 1}.mp3", "wb") as f:
async for message in ws:
event = json.loads(message)
if event["type"] == "audio.delta":
f.write(base64.b64decode(event["delta"]))
elif event["type"] == "audio.done":
break
elif event["type"] == "error":
raise RuntimeError(event)
asyncio.run(main())Node.js
Dùng thư viện ws (npm install ws).
import fs from "node:fs";
import WebSocket from "ws";
const url = "wss://api.88api.ai/v1/tts?model=grok-tts&voice=ara&codec=mp3&language=vi";
const ws = new WebSocket(url, {
headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
const chunks = [];
ws.on("open", () => {
for (const delta of ["Tôi đẩy cửa ra, ", "[pause] và nó ở ngay đó. ", "<whisper>Đây là bí mật.</whisper>"]) {
ws.send(JSON.stringify({ type: "text.delta", delta }));
}
ws.send(JSON.stringify({ type: "text.done" }));
});
ws.on("message", (data) => {
const event = JSON.parse(data.toString());
if (event.type === "audio.delta") {
chunks.push(Buffer.from(event.delta, "base64"));
} else if (event.type === "audio.done") {
fs.writeFileSync("speech.mp3", Buffer.concat(chunks));
ws.close();
} else if (event.type === "error") {
console.error(event);
ws.close();
}
});Chuyển giọng nói thành văn bản Grok (grok-stt)
cURL
Tải âm thanh lên bằng multipart/form-data. Hãy để cURL hoặc SDK tự tạo multipart boundary; không tự đặt header Content-Type: multipart/form-data.
curl --fail-with-body https://api.88api.ai/v1/audio/transcriptions \
-H "Authorization: Bearer $API_KEY" \
-F "model=grok-stt" \
-F "language=vi" \
-F "keyterm=88API" \
-F "file=@./meeting.mp3"Phản hồi:
{
"text": "Chào mừng bạn đến với dịch vụ tổng hợp giọng nói 88API. Hôm nay là ngày 17 tháng 10 năm 2026."
}Trường yêu cầu
| Trường | Kiểu | Bắt buộc | Mặc định | Mô tả |
|---|---|---|---|---|
file | file | Có | — | Tệp âm thanh hoặc video, hỗ trợ mp3, wav, ogg, opus, flac, aac, m4a, mp4, mkv; webm ghi từ trình duyệt cũng được |
model | string | Có | — | grok-stt |
response_format | string | Không | json | json, text, verbose_json; srt, vtt sẽ trả về 400 |
language | string | Không | Tự động nhận dạng | Mã ngôn ngữ, như zh, en, ja, yue (tiếng Quảng Đông); chỉ định ngôn ngữ giúp nhận dạng ổn định hơn |
format | boolean | Không | false | Khi là true, chuyển số, số tiền… theo cách nói sang cách viết; cần truyền kèm language |
keyterm | string | Không | — | Danh từ riêng cần ưu tiên nhận dạng, ví dụ tên sản phẩm như 88API, tên người; có thể truyền nhiều lần, mỗi lần một từ |
filler_words | boolean | Không | false | Khi là true, giữ lại các từ đệm như “ừm”, “ờ”; mặc định sẽ loại bỏ |
Các trường prompt, temperature, timestamp_granularities của OpenAI không có tác dụng với grok-stt và sẽ bị bỏ qua. Khi cần mô hình nhận đúng danh từ riêng, hãy dùng keyterm.
Định dạng phản hồi
response_format | Content-Type | Nội dung |
|---|---|---|
json | application/json | {"text": "..."} |
text | text/plain | Văn bản thuần |
verbose_json | application/json | text, language, duration (giây), cùng mốc thời gian theo từng từ words (word, start, end) |
Ví dụ verbose_json:
{
"task": "transcribe",
"language": "vi",
"duration": 6.456,
"text": "Chào mừng bạn đến với dịch vụ tổng hợp giọng nói 88API. Hôm nay là ngày 17 tháng 10 năm 2026.",
"words": [
{ "word": "Chào", "start": 0.08, "end": 0.241 },
{ "word": "mừng", "start": 0.261, "end": 0.421 }
]
}Python (OpenAI SDK)
from openai import OpenAI
client = OpenAI(
api_key="YOUR_88API_KEY",
base_url="https://api.88api.ai/v1",
)
with open("meeting.mp3", "rb") as audio_file:
result = client.audio.transcriptions.create(
model="grok-stt",
file=audio_file,
language="vi",
response_format="verbose_json",
extra_body={"format": "true", "keyterm": "88API"},
)
print(result.text, result.duration)Node.js (OpenAI SDK)
import fs from "node:fs";
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.API_KEY,
baseURL: "https://api.88api.ai/v1",
});
const transcription = await client.audio.transcriptions.create({
model: "grok-stt",
file: fs.createReadStream("meeting.mp3"),
language: "vi",
});
console.log(transcription.text);Hội thoại giọng nói thời gian thực Grok (grok-voice)
Trò chuyện bằng giọng nói theo thời gian thực với mô hình qua một kết nối WebSocket: gửi văn bản hoặc âm thanh từ micro, mô hình trả lời trực tiếp bằng giọng nói, đồng thời kèm bản ghi văn bản. Phù hợp cho trợ lý giọng nói, chăm sóc khách hàng qua điện thoại, luyện nói và các tình huống tương tự.
| Mô hình | Mô tả |
|---|---|
grok-voice-latest | Luôn trỏ tới phiên bản mới nhất, hiện là grok-voice-3.0 |
grok-voice-3.0 | Phiên bản cố định |
Kết nối
wss://api.88api.ai/v1/realtime?model=grok-voice-latest
Authorization: Bearer $API_KEYGiao thức sự kiện giống với xAI Realtime. Sau khi kết nối thành công, máy chủ gửi trước session.created và conversation.created, sau đó client thiết lập phiên và bắt đầu hội thoại.
- Mặc định, âm thanh được mã hóa Base64 và đặt trong sự kiện JSON để gửi và nhận. Cũng có thể chuyển sang truyền nhị phân, khi đó âm thanh thô đi thẳng qua frame nhị phân của WebSocket, xem Truyền âm thanh nhị phân.
- WebSocket của trình duyệt không thể đặt header
Authorization, và cũng không nên để lộ API Key ở frontend. Hãy thiết lập kết nối trên máy chủ của bạn, rồi chuyển tiếp âm thanh tới trình duyệt hoặc ứng dụng. - Định dạng âm thanh: cả đầu vào và đầu ra đều là PCM16 (16-bit little-endian), 24 kHz, mono.
Thiết lập phiên
{
"type": "session.update",
"session": {
"voice": "eve",
"instructions": "Bạn là trợ lý giọng nói của 88API, hãy trả lời ngắn gọn.",
"turn_detection": { "type": "server_vad" }
}
}| Trường | Mô tả |
|---|---|
voice | Giọng dùng để trả lời, giống 28 giọng của grok-tts (xem bảng giọng đọc ở trên), không phân biệt chữ hoa/thường, mặc định ara |
instructions | Chỉ dẫn hệ thống, thiết lập vai trò, giọng điệu, độ dài câu trả lời… |
turn_detection | {"type": "server_vad"}: máy chủ tự động trả lời khi phát hiện bạn đã nói xong; null (mặc định): cần tự commit âm thanh và yêu cầu trả lời |
- Khi
voicekhông có trong bảng giọng đọc (kể cả tên giọng của OpenAI), sẽ nhận sự kiệnerrorvớierror.paramlàsession.voice. Toàn bộ lầnsession.updatenày không có hiệu lực, kết nối vẫn được giữ; sửa lại rồi gửi lại là được. session.updatedkhông trả lại giọng đọc. Giọng hiện tại chỉ hiển thị trongsession.createdkhi kết nối, ví dụ giọng mặc địnhxai_ara.
Sự kiện phía client
| Sự kiện | Mô tả |
|---|---|
session.update | Thiết lập giọng đọc, chỉ dẫn hệ thống và phát hiện lượt nói |
conversation.item.create | Gửi một tin nhắn văn bản (input_text trong content) |
response.create | Yêu cầu mô hình trả lời |
input_audio_buffer.append | Nối thêm một đoạn âm thanh, audio là dữ liệu PCM16 mã hóa Base64, nên khoảng 100 ms mỗi lần |
input_audio_buffer.commit | Commit phần âm thanh đã nối thành một tin nhắn người dùng; dùng khi turn_detection là null |
Gửi văn bản:
{"type": "conversation.item.create", "item": {"type": "message", "role": "user", "content": [{"type": "input_text", "text": "Hãy giới thiệu bản thân trong một câu."}]}}
{"type": "response.create"}Gửi giọng nói: gửi liên tục input_audio_buffer.append. Khi bật server_vad, một khoảng lặng sau khi nói xong sẽ kích hoạt trả lời tự động; khi turn_detection là null, gửi xong âm thanh thì gửi tiếp input_audio_buffer.commit và response.create.
Sự kiện phía máy chủ
| Sự kiện | Mô tả |
|---|---|
session.created, session.updated | Phiên đã được tạo, thiết lập đã có hiệu lực |
input_audio_buffer.speech_started / speech_stopped | server_vad phát hiện bắt đầu nói, ngừng nói |
conversation.item.input_audio_transcription.completed | Văn bản nhận dạng từ giọng nói của người dùng, nằm trong transcript |
response.output_audio.delta | Đoạn âm thanh trả lời, delta là PCM16 24 kHz mono mã hóa Base64 |
response.output_audio_transcript.delta / .done | Bản ghi văn bản của câu trả lời; transcript trong .done là văn bản đầy đủ |
response.done | Kết thúc lượt trả lời này |
ping | Heartbeat, có thể bỏ qua |
error | Lỗi, chi tiết trong error.message và error.code |
Gửi tin nhắn văn bản này với thiết lập phiên ở trên, phản hồi thực tế (trích đoạn):
{"type": "response.output_audio_transcript.delta", "delta": "Tôi là trợ lý giọng nói của 88API."}
{"type": "response.output_audio.delta", "delta": "<âm thanh Base64>"}
{"type": "response.output_audio_transcript.done", "transcript": "Tôi là trợ lý giọng nói của 88API."}
{"type": "response.output_audio.done"}
{"type": "response.done", "response": {"status": "completed", "output": [{"type": "message", "role": "assistant", "content": [{"type": "audio", "transcript": "Tôi là trợ lý giọng nói của 88API."}]}]}}Tính phí
- Tính phí theo thời lượng cuộc gọi: cộng dồn theo giây từ lúc kết nối được thiết lập đến khi ngắt, thời gian rảnh không ai nói cũng được tính; dùng xong hãy đóng kết nối ngay. Giá xem tại Thị trường mô hình trong bảng điều khiển.
- Mỗi tin nhắn văn bản của người dùng (
conversation.item.createcóinput_text) tính thêm một khoản phí nhỏ; đầu vào giọng nói và câu trả lời bằng giọng nói của mô hình không tính phí riêng. - Khi số dư hoặc hạn mức của token không đủ phí cho 1 phút cuộc gọi, ngay sau khi kết nối sẽ nhận
error(codelàinsufficient_user_quota) và bị ngắt. Khi hết số dư giữa cuộc gọi, trong vòng 30 giây sẽ nhậnerrortương tự, sau đó kết nối bị ngắt với mã đóng1008.
Python
Cần websockets phiên bản 14 trở lên (pip install websockets). Ví dụ dưới đây gửi một tin nhắn văn bản và lưu câu trả lời bằng giọng nói thành reply.wav:
import asyncio
import base64
import json
import wave
import websockets
API_KEY = "YOUR_88API_KEY"
URL = "wss://api.88api.ai/v1/realtime?model=grok-voice-latest"
async def main():
async with websockets.connect(
URL, additional_headers={"Authorization": f"Bearer {API_KEY}"}
) as ws:
await ws.send(json.dumps({
"type": "session.update",
"session": {
"voice": "eve",
"instructions": "Bạn là trợ lý giọng nói của 88API, hãy trả lời ngắn gọn.",
"turn_detection": {"type": "server_vad"},
},
}))
await ws.send(json.dumps({
"type": "conversation.item.create",
"item": {
"type": "message",
"role": "user",
"content": [{"type": "input_text", "text": "Hãy giới thiệu bản thân trong một câu."}],
},
}))
await ws.send(json.dumps({"type": "response.create"}))
audio = bytearray()
async for message in ws:
event = json.loads(message)
if event["type"] == "response.output_audio.delta":
audio += base64.b64decode(event["delta"])
elif event["type"] == "response.output_audio_transcript.done":
print("Bản ghi:", event["transcript"])
elif event["type"] == "response.done":
break
elif event["type"] == "error":
raise RuntimeError(event)
with wave.open("reply.wav", "wb") as f:
f.setnchannels(1)
f.setsampwidth(2)
f.setframerate(24000)
f.writeframes(bytes(audio))
asyncio.run(main())Khi gửi giọng nói, hãy chia âm thanh 24 kHz, 16-bit, mono thành từng đoạn để gửi. Lấy phiên đã bật server_vad ở trên làm ví dụ, có thể dùng đoạn mã sau thay cho hai tin nhắn gửi văn bản:
with wave.open("question.wav", "rb") as f: # 24 kHz, 16-bit, mono
pcm = f.readframes(f.getnframes())
pcm += b"\x00" * 48000 # thêm 1 giây im lặng ở cuối để server_vad xác định đã nói xong
for i in range(0, len(pcm), 4800): # mỗi lần 100 ms
await ws.send(json.dumps({
"type": "input_audio_buffer.append",
"audio": base64.b64encode(pcm[i:i + 4800]).decode(),
}))Với đầu vào micro thời gian thực, chỉ cần gửi trực tiếp âm thanh thu được, không cần thêm khoảng lặng.
Node.js
Dùng thư viện ws (npm install ws). Ví dụ này tắt server_vad, sau khi gửi văn bản thì tự yêu cầu trả lời và lưu câu trả lời thành reply.wav:
import fs from "node:fs";
import WebSocket from "ws";
const ws = new WebSocket("wss://api.88api.ai/v1/realtime?model=grok-voice-latest", {
headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
const send = (event) => ws.send(JSON.stringify(event));
const chunks = [];
// Thêm header WAV cho dữ liệu PCM16 24 kHz mono
function toWav(pcm, rate = 24000) {
const header = Buffer.alloc(44);
header.write("RIFF", 0);
header.writeUInt32LE(36 + pcm.length, 4);
header.write("WAVEfmt ", 8);
header.writeUInt32LE(16, 16);
header.writeUInt16LE(1, 20);
header.writeUInt16LE(1, 22);
header.writeUInt32LE(rate, 24);
header.writeUInt32LE(rate * 2, 28);
header.writeUInt16LE(2, 32);
header.writeUInt16LE(16, 34);
header.write("data", 36);
header.writeUInt32LE(pcm.length, 40);
return Buffer.concat([header, pcm]);
}
ws.on("open", () => {
send({
type: "session.update",
session: { voice: "rex", instructions: "Trả lời trong một câu.", turn_detection: null },
});
send({
type: "conversation.item.create",
item: {
type: "message",
role: "user",
content: [{ type: "input_text", text: "Thủ đô của Pháp là gì?" }],
},
});
send({ type: "response.create" });
});
ws.on("message", (data) => {
const event = JSON.parse(data.toString());
switch (event.type) {
case "response.output_audio.delta":
chunks.push(Buffer.from(event.delta, "base64"));
break;
case "response.output_audio_transcript.delta":
process.stdout.write(event.delta);
break;
case "response.done":
fs.writeFileSync("reply.wav", toWav(Buffer.concat(chunks)));
ws.close();
break;
case "error":
console.error(event.error);
ws.close();
break;
}
});Truyền âm thanh nhị phân
Sau khi đặt transport của đầu vào và đầu ra thành "binary" trong session.update, âm thanh PCM thô được gửi và nhận trực tiếp dưới dạng frame nhị phân WebSocket, không cần mã hóa/giải mã Base64:
{
"type": "session.update",
"session": {
"turn_detection": null,
"audio": {
"input": { "format": { "type": "audio/pcm", "rate": 24000 }, "transport": "binary" },
"output": { "format": { "type": "audio/pcm", "rate": 24000 }, "transport": "binary" }
}
}
}- Gửi: mỗi frame nhị phân là một đoạn âm thanh thô PCM16, 24 kHz, mono, nên dùng 100 ms mỗi frame (4800 byte), thay cho
input_audio_buffer.append. - Nhận: âm thanh trả lời được trả về dưới dạng frame nhị phân, không còn sự kiện
response.output_audio.delta; chỉ cần nối lại theo thứ tự nhận được. - Các sự kiện điều khiển như
input_audio_buffer.commit,response.create, cùng các sự kiện phía máy chủ nhưsession.updated, bản ghi văn bản,response.donevẫn là frame văn bản JSON. - Cách tính phí không đổi.
Ví dụ Python: gửi một câu hỏi bằng giọng nói và lưu câu trả lời bằng giọng nói thành reply.wav:
import asyncio
import json
import wave
import websockets
API_KEY = "YOUR_88API_KEY"
URL = "wss://api.88api.ai/v1/realtime?model=grok-voice-latest"
PCM = {"type": "audio/pcm", "rate": 24000}
async def main():
async with websockets.connect(
URL, additional_headers={"Authorization": f"Bearer {API_KEY}"}
) as ws:
await ws.send(json.dumps({
"type": "session.update",
"session": {
"voice": "eve",
"turn_detection": None,
"audio": {
"input": {"format": PCM, "transport": "binary"},
"output": {"format": PCM, "transport": "binary"},
},
},
}))
with wave.open("question.wav", "rb") as f: # 24 kHz, 16-bit, mono
pcm = f.readframes(f.getnframes())
for i in range(0, len(pcm), 4800): # mỗi frame 100 ms, gửi trực tiếp PCM thô
await ws.send(pcm[i:i + 4800])
await ws.send(json.dumps({"type": "input_audio_buffer.commit"}))
await ws.send(json.dumps({"type": "response.create"}))
audio = bytearray()
async for message in ws:
if isinstance(message, bytes): # frame nhị phân: âm thanh trả lời
audio += message
continue
event = json.loads(message) # frame văn bản: sự kiện điều khiển
if event["type"] == "response.output_audio_transcript.done":
print("Bản ghi:", event["transcript"])
elif event["type"] == "response.done":
break
elif event["type"] == "error":
raise RuntimeError(event)
with wave.open("reply.wav", "wb") as f:
f.setnchannels(1)
f.setsampwidth(2)
f.setframerate(24000)
f.writeframes(bytes(audio))
asyncio.run(main())Tổng hợp giọng nói Gemini
Hiện tổng hợp giọng nói Gemini chỉ có gemini-3.8-flash-tts, gọi qua endpoint gốc của Gemini, không hỗ trợ /v1/audio/speech (sẽ trả về 500 “模型没有返回音频” (model không trả về âm thanh), không bị trừ phí). Các mô hình cũ gemini-3.1-flash-tts, gemini-3.8-flash-lite-tts, gemini-2.5-flash-tts, gemini-2.5-pro-tts đã ngừng cung cấp; khi cần /v1/audio/speech hoặc âm thanh streaming, hãy dùng Tổng hợp giọng nói Grok.
cURL
Khóa vẫn là API key của 88API, có thể đặt trong header x-goog-api-key.
curl --fail-with-body "https://api.88api.ai/v1beta/models/gemini-3.8-flash-tts:generateContent" \
-H "x-goog-api-key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [{ "role": "user", "parts": [{ "text": "Chào mừng bạn đến với dịch vụ tổng hợp giọng nói 88API.<laugh> Hôm nay trời đẹp quá." }] }],
"generationConfig": {
"responseModalities": ["AUDIO"],
"speechConfig": {
"voiceConfig": { "prebuiltVoiceConfig": { "voiceName": "Kore" } }
}
}
}'Phản hồi và tải xuống
Phản hồi là JSON, không chứa dữ liệu âm thanh, mà trả về một liên kết tải âm thanh trong candidates[0].content.parts[0].text, ở dạng liên kết Markdown (chữ hiển thị của liên kết luôn là “生成音频”, nghĩa là “âm thanh đã tạo”):
{
"candidates": [{
"content": {
"role": "model",
"parts": [{ "text": "[生成音频](https://example.com/contents/xxxxxxxx.wav)" }]
},
"finishReason": "STOP"
}]
}- Lấy địa chỉ trong ngoặc tròn của văn bản để tải xuống, việc tải không cần API key. Âm thanh là tệp WAV (24 kHz, 16-bit, đơn kênh).
- Liên kết chỉ được giữ vài giờ, hết hạn sẽ không tải được nữa; hãy tải xuống và lưu lại ngay sau khi nhận phản hồi.
- Tính phí theo Token đầu vào và đầu ra, giá lấy theo hiển thị tại Thị trường mô hình trong bảng điều khiển.
- Endpoint streaming
POST /v1beta/models/gemini-3.8-flash-tts:streamGenerateContent?alt=ssegọi được, nhưng không trả âm thanh theo từng đoạn: sau khi tổng hợp xong sẽ trả cùng liên kết tải đó trong một sự kiện duy nhất.
Quy tắc đọc
- Đọc nguyên văn: mọi chữ trong văn bản đều sẽ được đọc ra. Đừng viết chỉ dẫn kiểu “Hãy nói bằng giọng vui vẻ:” trong văn bản, nếu không câu đó cũng sẽ bị đọc ra.
- Giọng điệu được điều khiển bằng thẻ trong ngoặc nhọn trong văn bản, bản thân thẻ không bị đọc ra, ví dụ
<laugh>(cười),<short pause>(ngắt ngắn),<whispers>(thì thầm),<sigh>(thở dài).
Giọng đọc
Chỉ định trong speechConfig.voiceConfig.prebuiltVoiceConfig.voiceName, có tổng cộng 30 giọng có sẵn. Mô tả phong cách lấy từ bảng giọng đọc chính thức của Google; mọi giọng đều đọc được nhiều ngôn ngữ, trong đó có tiếng Trung.
| Giọng đọc | Phong cách | Giới tính |
|---|---|---|
Achernar | Nhẹ nhàng | Nữ |
Achird | Thân thiện | Nam |
Algenib | Khàn | Nam |
Algieba | Mượt mà | Nam |
Alnilam | Chắc chắn | Nam |
Aoede | Thoáng đãng | Nữ |
Autonoe | Tươi sáng | Nữ |
Callirrhoe | Dễ chịu | Nữ |
Charon | Giàu thông tin | Nam |
Despina | Mượt mà | Nữ |
Enceladus | Nhiều hơi thở | Nam |
Erinome | Rõ ràng | Nữ |
Fenrir | Hào hứng | Nam |
Gacrux | Chín chắn | Nữ |
Iapetus | Rõ ràng | Nam |
Kore | Chắc chắn | Nữ |
Laomedeia | Vui tươi | Nữ |
Leda | Trẻ trung | Nữ |
Orus | Chắc chắn | Nam |
Puck | Vui tươi | Nam |
Pulcherrima | Thẳng thắn | Nữ |
Rasalgethi | Giàu thông tin | Nam |
Sadachbia | Sôi nổi | Nam |
Sadaltager | Uyên bác | Nam |
Schedar | Đều đặn | Nam |
Sulafat | Ấm áp | Nữ |
Umbriel | Dễ chịu | Nam |
Vindemiatrix | Dịu dàng | Nữ |
Zephyr | Tươi sáng | Nữ |
Zubenelgenubi | Thoải mái | Nam |
Nếu chưa chắc, hãy thử trước Kore (nữ) và Charon (nam). Cập nhật về giọng đọc và ngôn ngữ lấy theo tài liệu chính thức Google Gemini-TTS.
Hội thoại hai người
Thay voiceConfig trong speechConfig bằng multiSpeakerVoiceConfig, chỉ định giọng đọc riêng cho tối đa 2 người nói. Mỗi dòng văn bản chỉ viết “Tên: lời thoại”, đừng thêm chỉ dẫn kiểu “TTS the following conversation…” (sẽ bị đọc ra):
{
"contents": [{
"role": "user",
"parts": [{ "text": "Joe: How's it going today Jane?\nJane: Not too bad, how about you?" }]
}],
"generationConfig": {
"responseModalities": ["AUDIO"],
"speechConfig": {
"multiSpeakerVoiceConfig": {
"speakerVoiceConfigs": [
{ "speaker": "Joe", "voiceConfig": { "prebuiltVoiceConfig": { "voiceName": "Charon" } } },
{ "speaker": "Jane", "voiceConfig": { "prebuiltVoiceConfig": { "voiceName": "Kore" } } }
]
}
}
}
}Cách trả về giống hội thoại một người, cũng là một liên kết tải WAV.
Chuyển giọng nói thành văn bản Gemini
| Mô hình | Ghi chú |
|---|---|
gemini-3-stt | Khuyên dùng cho chuyển ghi thông thường, cuộc họp, phụ đề |
gemini-3.5-stt | Cho âm thanh phức tạp hơn; đơn giá cao hơn |
gemini-3.5-transcribe | Mô hình chuyên dùng để chuyển ghi, tự nhận dạng hơn 85 ngôn ngữ, mỗi lần tối đa khoảng 1 giờ âm thanh, tốc độ nhanh |
Ba mô hình được gọi theo cùng một cách; chỉ cần đổi sang tên mô hình khác trong các ví dụ bên dưới, điểm khác biệt của gemini-3.5-transcribe xem tại gemini-3.5-transcribe. Có ba cách gọi: tải tệp lên /v1/audio/transcriptions (khuyến nghị), truyền âm thanh qua endpoint hội thoại, hoặc dùng endpoint gốc của Gemini.
Tải tệp lên để chuyển ghi (khuyến nghị)
Giống grok-stt, dùng multipart/form-data; không tự đặt header Content-Type: multipart/form-data.
curl --fail-with-body https://api.88api.ai/v1/audio/transcriptions \
-H "Authorization: Bearer $API_KEY" \
-F "model=gemini-3-stt" \
-F "language=vi" \
-F "file=@./meeting.mp3"Phản hồi:
{
"text": "Chào mừng bạn đến với dịch vụ tổng hợp giọng nói 88 API. Hôm nay là ngày 17 tháng 10 năm 2026."
}| Trường | Kiểu | Bắt buộc | Mặc định | Mô tả |
|---|---|---|---|---|
file | file | Có | — | Tệp âm thanh, các định dạng phổ biến như mp3, wav, m4a, ogg, flac đều được; tối đa 25 MB |
model | string | Có | — | gemini-3-stt, gemini-3.5-stt hoặc gemini-3.5-transcribe |
response_format | string | Không | json | json ({"text": "..."}), text (văn bản thuần), verbose_json (thêm task, language, duration); srt, vtt sẽ trả về 400 |
language | string | Không | Tự động nhận dạng | Mã ngôn ngữ, như zh, en, yue (tiếng Quảng Đông) |
prompt | string | Không | — | Gợi ý về tình huống, tên người, thuật ngữ… để giúp nhận dạng; không có tác dụng với gemini-3.5-transcribe |
verbose_json không có mốc thời gian theo từng từ (words) hay phân đoạn (segments); khi cần mốc thời gian theo từng từ, hãy dùng grok-stt hoặc endpoint gốc của gemini-3.5-transcribe. Tệp vượt quá 25 MB sẽ trả về 400; hãy nén (ví dụ chuyển sang MP3 mono 16 kHz) hoặc chia đoạn rồi chuyển ghi.
Python (OpenAI SDK):
from openai import OpenAI
client = OpenAI(
api_key="YOUR_88API_KEY",
base_url="https://api.88api.ai/v1",
)
with open("meeting.mp3", "rb") as audio_file:
result = client.audio.transcriptions.create(
model="gemini-3-stt",
file=audio_file,
language="vi",
)
print(result.text)Endpoint hội thoại (đầu vào âm thanh)
Đặt âm thanh dạng Base64 vào tin nhắn hội thoại; mô hình xuất kết quả chuyển ghi theo chỉ dẫn văn bản của bạn. Bạn có thể mô tả tình huống, tên người và thuật ngữ trong chỉ dẫn để giúp mô hình nhận dạng chính xác.
cURL
Trước tiên chuyển âm thanh sang Base64, rồi đặt vào input_audio:
AUDIO_B64=$(base64 < meeting.mp3 | tr -d '\n')
cat > request.json <<EOF
{
"model": "gemini-3-stt",
"messages": [{
"role": "user",
"content": [
{ "type": "text", "text": "Hãy chuyển đoạn âm thanh này thành văn bản, chỉ xuất kết quả chuyển ghi." },
{ "type": "input_audio", "input_audio": { "data": "$AUDIO_B64", "format": "mp3" } }
]
}]
}
EOF
curl --fail-with-body https://api.88api.ai/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
--data-binary @request.jsonKết quả chuyển ghi nằm ở choices[0].message.content. format điền định dạng âm thanh, như mp3, wav.
Python (OpenAI SDK)
import base64
from openai import OpenAI
client = OpenAI(
api_key="YOUR_88API_KEY",
base_url="https://api.88api.ai/v1",
)
with open("meeting.mp3", "rb") as f:
audio_b64 = base64.b64encode(f.read()).decode()
completion = client.chat.completions.create(
model="gemini-3-stt",
messages=[{
"role": "user",
"content": [
{"type": "text", "text": "Hãy chuyển đoạn âm thanh này thành văn bản, chỉ xuất kết quả chuyển ghi."},
{"type": "input_audio", "input_audio": {"data": audio_b64, "format": "mp3"}},
],
}],
)
print(completion.choices[0].message.content)Node.js (OpenAI SDK)
import fs from "node:fs";
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.API_KEY,
baseURL: "https://api.88api.ai/v1",
});
const audio = fs.readFileSync("meeting.mp3").toString("base64");
const completion = await client.chat.completions.create({
model: "gemini-3-stt",
messages: [{
role: "user",
content: [
{ type: "text", text: "Hãy chuyển đoạn âm thanh này thành văn bản, chỉ xuất kết quả chuyển ghi." },
{ type: "input_audio", input_audio: { data: audio, format: "mp3" } },
],
}],
});
console.log(completion.choices[0].message.content);Endpoint gốc của Gemini
{
"contents": [{
"role": "user",
"parts": [
{ "text": "Hãy chuyển đoạn âm thanh này thành văn bản, chỉ xuất kết quả chuyển ghi." },
{ "inlineData": { "mimeType": "audio/wav", "data": "<âm thanh Base64>" } }
]
}]
}Gửi tới POST https://api.88api.ai/v1beta/models/gemini-3-stt:generateContent, kèm header x-goog-api-key: $API_KEY.
Endpoint hội thoại và endpoint gốc đặt âm thanh trong thân yêu cầu dưới dạng Base64, phù hợp với bản ghi ngắn; với tệp lớn hơn, hãy dùng cách tải tệp lên để chuyển ghi. Các mô hình đã ngừng gemini-2.5-stt, gemini-3.6-stt hãy chuyển sang gemini-3-stt, gemini-3.5-stt hoặc grok-stt.
gemini-3.5-transcribe
Mô hình chuyên dùng để chuyển ghi, chỉ cần âm thanh, không cần và cũng không nhận chỉ dẫn văn bản:
/v1/audio/transcriptions:languageđiền mã ngôn ngữ BCP-47, nhưzh,en,yue, mã không hợp lệ trả về400;promptkhông có tác dụng. Mô hình không trả về ngôn ngữ nhận dạng được;languagetrongverbose_jsonlà giá trị bạn truyền vào, không truyền thì là chuỗi rỗng.- Endpoint hội thoại: văn bản trong tin nhắn bị bỏ qua và không tính phí, chỉ cần gửi
input_audio; kèm tin nhắnsystemhoặcreasoning_effortsẽ trả về400. - Endpoint gốc: có thể dùng
generationConfig.audioTranscriptionConfigđể chỉ định ngôn ngữ, từ vựng tùy chỉnh, phân biệt người nói và mốc thời gian theo từng từ. - Không hỗ trợ chuyển ghi streaming thời gian thực.
Ví dụ endpoint gốc:
curl --fail-with-body "https://api.88api.ai/v1beta/models/gemini-3.5-transcribe:generateContent" \
-H "x-goog-api-key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [{
"role": "user",
"parts": [{ "inlineData": { "mimeType": "audio/wav", "data": "<âm thanh Base64>" } }]
}],
"generationConfig": {
"audioTranscriptionConfig": { "diarization": true, "wordTimestamp": true }
}
}'Trường audioTranscriptionConfig | Kiểu | Mô tả |
|---|---|---|
languageCodes | string[] | Ngôn ngữ của âm thanh, mã BCP-47, như ["zh"]; không truyền thì tự động nhận dạng |
customVocabulary | string[] | Danh từ riêng cần ưu tiên nhận dạng, như ["88API"]; các từ này được tính vào lượng đầu vào |
diarization | boolean | Phân biệt người nói, mỗi đoạn kết quả có speakerLabel (tính năng thử nghiệm) |
wordTimestamp | boolean | Trả về mốc thời gian theo từng từ words (tính năng thử nghiệm) |
mode | string | SMART: chế độ chuyển ghi thông minh, thời gian xử lý lâu hơn; không dùng cùng lúc với diarization, wordTimestamp, nếu không sẽ trả về 400 |
Phản hồi thực tế cho một đoạn hội thoại hai người (candidates[0].content.parts, trích một phần):
[
{
"text": "How's it going today, Jane?",
"audioTranscription": {
"text": "How's it going today, Jane?",
"speakerLabel": "spk:0",
"words": [
{ "word": "How's", "startOffset": "0.200s", "endOffset": "0.300s" },
{ "word": "it", "startOffset": "0.300s", "endOffset": "0.400s" }
]
}
},
{
"text": "Not too bad. How about you?",
"audioTranscription": {
"text": "Not too bad. How about you?",
"speakerLabel": "spk:1",
"words": [
{ "word": "Not", "startOffset": "2.100s", "endOffset": "2.200s" }
]
}
}
]Khi không bật phân biệt người nói, toàn bộ kết quả chuyển ghi nằm trong parts[0].text. Phân biệt người nói và mốc thời gian theo từng từ là tính năng thử nghiệm: âm thanh trộn tiếng Trung và tiếng Anh có thể mất các đoạn thuộc ngôn ngữ không chính; khi cần văn bản đầy đủ, hãy tắt hai tùy chọn này.
Lỗi thường gặp
| Mã trạng thái | Nguyên nhân thường gặp | Cách xử lý |
|---|---|---|
400 | Thiếu input / file, tên giọng không có trong bảng giọng đọc (kể cả tên giọng của OpenAI), định dạng hoặc tần số lấy mẫu không được hỗ trợ, speed vượt phạm vi, văn bản quá dài, tệp tải lên vượt quá 25 MB | Sửa yêu cầu theo thông báo lỗi và mô tả trường trong trang này |
400 | Gọi mô hình giọng nói qua endpoint hội thoại, Responses hoặc Messages | Chuyển sang endpoint tương ứng trong trang này |
400 | Văn bản bị chính sách an toàn chặn (PROHIBITED_CONTENT) | Sửa văn bản rồi thử lại; gửi lại cùng nội dung sẽ không giải quyết được |
401 | Thiếu API Key hoặc API Key không hợp lệ | Kiểm tra Bearer Token, không để lộ khóa trong mã phía trình duyệt |
429 | Giới hạn tốc độ, hạn mức hoặc năng lực | Thử lại với backoff lũy thừa và kiểm tra số dư tài khoản |
500 / 502 / 503 | Lỗi tạm thời phía máy chủ hoặc phía nguồn | Thử lại số lần có giới hạn; nếu vẫn lỗi, liên hệ hỗ trợ kèm ID yêu cầu |
request id trong phản hồi lỗi là căn cứ để điều tra, hãy lưu lại trong log; không ghi API Key, âm thanh riêng tư hoặc nội dung chuyển ghi nhạy cảm.