🔊 Text-to-Speech API

Chuyển văn bản thành giọng nói tự nhiên (audio) với hơn 20 model từ OpenAI, Google, ElevenLabs, Microsoft, Deepgram và nhiều hãng khác — cùng một endpoint, chỉ đổi model. API tương thích hoàn toàn với OpenAI SDK — chỉ cần đổi base_url.

Không cần viết code: có thể chuyển văn bản thành giọng nói ngay trong AI Studio (có model miễn phí). Video hướng dẫn:

2:18

Endpoint

POST https://platform.beeknoee.com/v1/audio/speech
GET  https://platform.beeknoee.com/v1/audio/voices

✅ ElevenLabs v3 đã mở trên production (cập nhật 20/09/2026) — model elevenlabs/eleven_v3 (gọi thẳng ElevenLabs), 33 giọng, trong đó 12 giọng Việt bản địa (Bắc/Trung/Nam). Đây là model ElevenLabs duy nhất có giọng Việt.

🆕 08/10/2026 — thêm 6 model ElevenLabs qua nguồn đa hãng: elevenlabs/eleven-flash-v2, eleven-flash-v2.5, eleven-turbo-v2, eleven-turbo-v2.5, eleven-v3-conversational, eleven-v4-turbo — mỗi model 21 giọng tiếng Anh, không có giọng Việt; xem Model đa hãng. Lưu ý ID dùng gạch ngang (eleven-flash-v2.5), khác ID gốc của ElevenLabs (eleven_flash_v2_5 — không gọi được). eleven_multilingual_v2 chưa mở.

Các model khác đang dùng được: OpenAI (openai/tts-1, openai/tts-1-hd, openai/gpt-4o-mini-tts) và Google (google/google-tts miễn phí, google/gemini-2.5-flash-tts, google/gemini-2.5-pro-tts, google/gemini-3.1-flash-tts-preview).

🆕 03/10/2026 — thêm 10 model đa hãng: Microsoft MAI-Voice (có giọng tiếng Việt), Deepgram, Grok, Canopy Labs, Sesame, Hexgrad — xem Model đa hãng.

Danh sách chuẩn xác luôn xem tại trang Audio Models trên Dashboard.

💡 Mọi provider dùng chung endpoint /v1/audio/speech — kể cả ElevenLabs. Bạn KHÔNG cần gọi api.elevenlabs.io trực tiếp: hệ thống tự chuyển request sang API riêng của ElevenLabs (/v1/text-to-speech/{voice_id}) và trả audio về đúng format OpenAI. Chỉ cần đổi model là xong.

GET /v1/audio/voices là endpoint phụ để lấy danh sách voice của elevenlabs/eleven_v3 (kèm link nghe thử) — xem mục ElevenLabs Voices. Thêm ?model=<model ID> để lấy giọng của một model đa hãng (kể cả 6 model elevenlabs/eleven-*).

Request

Headers

Body Parameters

Giới hạn độ dài input

Mỗi model một mức khác nhau — trước đây hệ thống chặn cứng mọi model ở 4.096 ký tự (giới hạn riêng của OpenAI), nay đã bỏ để model nào cho dài hơn thì dùng được hết:

Vượt giới hạn sẽ nhận lỗi 400 kèm thông báo giới hạn thật của chính model đó, và không bị trừ tiền. Nhóm model đa hãng cũng vậy: mỗi model một mức, vượt thì báo 400, không trừ tiền.

⚠️ Lưu ý riêng cho elevenlabs/eleven_v3 (6 model elevenlabs/eleven-* theo luật của nhóm đa hãng):

• response_format chỉ hỗ trợ mp3, opus, pcm — gửi aac/flac/wav sẽ nhận lỗi 400.
• speed hợp lệ trong khoảng 0.7 – 1.2 — giá trị ngoài khoảng sẽ tự động clamp.
• voice nhận voice_id lấy từ GET /v1/audio/voices, hoặc alias OpenAI (nova, echo...). Giá trị không nằm trong danh sách sẽ bị từ chối với lỗi 400.

Models khả dụng

💰 Giá từng model xem tại trang Audio Models — đó là nơi duy nhất luôn khớp với bảng giá đang chạy. Docs cố ý không chép lại số — chép là sớm muộn cũng lệch.

🆓 Miễn phí

OpenAI Models

Google Gemini TTS

Từ 25/07/2026, 3 model Google Cloud TTS cũ (WaveNet, Neural2, Chirp 3 HD) đã được nâng cấp sang Gemini-TTS — thế hệ giọng mới nhất của Google, 30 giọng dùng chung cho mọi ngôn ngữ, tiếng Việt đã GA.

🔄 Model cũ đã đổi tên. Nếu code bạn đang gọi google/wavenet, google/neural2 hoặc google/chirp3-hd thì cần đổi sang model ID mới ở bảng trên. Voice name cũng đổi — xem mục Gemini TTS Voices.

Google Cloud TTS (giọng cổ điển)

ElevenLabs Models

ℹ️ Bản Flash / Turbo / v3 Conversational / v4 Turbo có dưới ID gạch ngang (elevenlabs/eleven-flash-v2.5…) trong nhóm đa hãng — không có giọng Việt; cần giọng Việt hãy dùng eleven_v3. ID gạch dưới kiểu eleven_flash_v2_5 và eleven_multilingual_v2 không mở — gọi vào sẽ báo model không tồn tại. Chép lời bằng Scribe: xem Speech-to-Text.

⚠️ Số giọng là 33, không phải "3.000+". Bạn chỉ dùng được các giọng có trong danh sách GET /v1/audio/voices — đó là kho giọng Beeknoee đã tuyển sẵn, gồm 21 giọng gốc ElevenLabs và 12 giọng Việt bản địa. Copy một voice_id bất kỳ từ Voice Library của ElevenLabs sẽ bị từ chối với lỗi 400.

Lưu ý phân biệt: giọng (voice) và model là hai thứ khác nhau. Giọng quyết định âm sắc, model quyết định cách phát âm. Cả 33 giọng đều chạy được với eleven_v3, và v3 hỗ trợ tiếng Việt nên giọng Việt đọc đúng dấu.

Con số 33 chỉ áp dụng cho eleven_v3. 6 model elevenlabs/eleven-* dùng danh mục 21 giọng riêng — lấy bằng GET /v1/audio/voices?model=<ID>.

Model đa hãng — giọng riêng từng model (từ 03/10/2026)

16 model của Microsoft, Deepgram, Grok, Canopy Labs, Sesame, Hexgrad và ElevenLabs (6 model elevenlabs/eleven-*, thêm 08/10/2026). Mỗi model có danh mục giọng riêng (tên giọng khác hẳn alias OpenAI) — lấy bằng GET /v1/audio/voices?model=.

⚠️ Lưu ý riêng cho nhóm model này:

• voice không bắt buộc — bỏ trống thì dùng giọng mặc định của model (có giọng tiếng Việt thì ưu tiên giọng Việt). Gửi giọng không có trong danh mục ⇒ lỗi 400 kèm danh sách giọng hợp lệ.
• response_format chỉ nhận mp3 hoặc pcm — định dạng khác báo lỗi 400 ngay, không trừ tiền.
• speed: đa số model không hỗ trợ — bỏ qua tham số này (một số model báo 400 nếu khác 1.0).
• Độ dài input tối đa khác nhau theo model — vượt giới hạn nhận lỗi 400, không trừ tiền.
• Model chỉ có giọng tiếng Anh vẫn nhận văn bản tiếng Việt nhưng đọc không chuẩn — cần tiếng Việt hãy dùng microsoft/mai-voice-2.1(-flash) hoặc elevenlabs/eleven_v3.

💡 Khuyến nghị: Dùng google/google-tts nếu muốn miễn phí hoàn toàn. Dùng google/gemini-2.5-flash-tts cho tiếng Việt tự nhiên, cân bằng giá. Dùng openai/tts-1 nếu cần độ trễ thấp và nhiều tùy chọn voice. Dùng elevenlabs/eleven_v3 khi cần giọng Việt giống người thật nhất — đọc truyện, audiobook, lồng tiếng video.

Voices — Danh sách chi tiết

OpenAI Voices (dùng cho openai/tts-1, openai/tts-1-hd, openai/gpt-4o-mini-tts)

11 giọng dưới đây dùng chung cho cả 3 model OpenAI. Tất cả đều hỗ trợ đa ngôn ngữ (tiếng Việt, Anh, Nhật, Hàn, Trung, Pháp...) — chỉ cần viết text bằng ngôn ngữ đó.

🎧 Nghe thử giọng nói: Truy cập openai.fm để test trực tiếp tất cả 11 voice trước khi chọn.

Ví dụ nhanh:

{ "model": "openai/tts-1", "voice": "nova", "input": "Xin chào!" }

Google Cloud Voices — Tiếng Việt (vi-VN)

🎧 Nghe thử giọng nói Google: Truy cập geminitts.net để test tất cả voice Google Cloud trước khi chọn.

Mỗi tier (Standard / WaveNet / Neural2 / Chirp-HD) có bộ voice riêng. Dùng đúng voice name tương ứng với model đã chọn.

Model google/standard — Giọng cơ bản

⚠️ Các tier WaveNet, Neural2, Chirp-HD không còn dùng voice name kiểu này — 3 model đó đã chuyển sang Gemini-TTS. Xem mục ngay dưới.

Ví dụ:

{ "model": "google/standard", "voice": "vi-VN-Standard-A", "input": "Xin chào!" }

Gemini TTS Voices — dùng cho 3 model google/gemini-*-tts

Khác giọng cổ điển ở 2 điểm quan trọng:

1. Tên giọng là tên trần, không có tiền tố ngôn ngữ. Đúng: Kore. Sai: vi-VN-Kore, vi-VN-Wavenet-A.
2. Cùng một bộ 30 giọng cho mọi ngôn ngữ — không phải mỗi ngôn ngữ một bộ riêng như trước. Ngôn ngữ được nhận từ chính nội dung input.

Ví dụ:

{ "model": "google/gemini-2.5-flash-tts", "voice": "Kore", "input": "Xin chào, đây là giọng Gemini." }

Mặc định ngôn ngữ là vi-VN. Muốn chỉ định rõ, thêm mã ngôn ngữ trước tên giọng:

{ "model": "google/gemini-2.5-flash-tts", "voice": "en-US-Puck", "input": "Hello from Beeknoee." }

Nhập giọng không tồn tại → hệ thống tự dùng Kore thay vì báo lỗi.

⚠️ Model Gemini TTS bỏ qua tham số speed. Google tính phí theo thời lượng audio nên tốc độ đọc bị khoá cố định. Giọng cổ điển (google/standard) vẫn nhận speed bình thường.

Google Cloud Voices — Tiếng Anh (en-US)

Cùng cấu trúc, thay vi-VN bằng en-US:

Hỗ trợ 40+ ngôn ngữ khác: ja-JP, ko-KR, zh-CN, fr-FR, de-DE... Thay prefix ngôn ngữ tương ứng.

Google Voices — dùng OpenAI alias

Quen tên voice OpenAI thì cứ gửi nguyên, hệ thống tự map. Bảng map khác nhau tuỳ model:

💡 Với Gemini TTS, alias mặc định đọc tiếng Việt (vi-VN). Với giọng cổ điển, alias chỉ map sang en-US.

Google TTS Free Voices (model google/google-tts)

Dùng mã ngôn ngữ 2 ký tự — giọng kiểu Google Translate:

Hỗ trợ 50+ ngôn ngữ. Dùng mã ISO 639-1 (2 ký tự) làm voice ID.

Ví dụ:

{ "model": "google/google-tts", "voice": "vi", "input": "Xin chào!" }

Giọng của model đa hãng

Mỗi model trong nhóm Model đa hãng có danh mục giọng riêng — lấy theo từng model:

curl "https://platform.beeknoee.com/v1/audio/voices?model=microsoft/mai-voice-2.1-flash" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "model": "microsoft/mai-voice-2.1-flash",
  "default_voice": "vi-VN-Grant:MAI-Voice-2.1-Flash",
  "voices": [
    { "voice_id": "vi-VN-Grant:MAI-Voice-2.1-Flash", "language": "vi-VN" },
    { "voice_id": "vi-VN-Harper:MAI-Voice-2.1-Flash", "language": "vi-VN" },
    { "voice_id": "en-US-Harper:MAI-Voice-2.1-Flash", "language": "en-US" }
  ]
}

Dùng nguyên voice_id (kể cả phần sau dấu :), hoặc bỏ trống voice để dùng default_voice:

{ "model": "microsoft/mai-voice-2.1-flash", "voice": "vi-VN-Harper:MAI-Voice-2.1-Flash", "input": "Xin chào!" }
{ "model": "microsoft/mai-voice-2.1-flash", "input": "Xin chào, đây là giọng mặc định." }

💡 Với model ngoài nhóm này, ?model= không đổi gì — GET /v1/audio/voices vẫn trả danh sách giọng của elevenlabs/eleven_v3 như cũ.

ElevenLabs Voices

Beeknoee cung cấp 33 giọng cho elevenlabs/eleven_v3: 21 giọng gốc ElevenLabs (tiếng Anh) và 12 giọng Việt bản địa.

ℹ️ 6 model elevenlabs/eleven-* (nhóm đa hãng) không dùng danh sách này — chúng có 21 giọng tên trần (george, sarah, adam, alice, bella, bill, brian, callum, charlie, chris, daniel, eric, harry, jessica, laura, liam, lily, matilda, river, roger, will), không có giọng Việt. Lấy bằng GET /v1/audio/voices?model=elevenlabs/eleven-v4-turbo (đổi ID tương ứng).

🔒 Chỉ dùng được giọng trong danh sách này. Truyền một voice_id bất kỳ copy từ Voice Library của ElevenLabs sẽ nhận lỗi 400 — kho giọng là do Beeknoee tuyển chọn, không mở tự do. Cần thêm giọng, hãy liên hệ hỗ trợ.

🇻🇳 12 giọng tiếng Việt

Nghe thử từng giọng bằng preview_url trong GET /v1/audio/voices, hoặc mở AI Studio → tab Audio → bấm ▶ cạnh ô chọn giọng.

Có 3 cách chọn voice cho model ElevenLabs:

Cách 1 — Dùng OpenAI alias (tự động map sang giọng ElevenLabs tương đương). Tiện khi bạn đang chuyển code từ OpenAI sang, nhưng đều là giọng tiếng Anh — nội dung tiếng Việt hãy dùng bảng ở trên:

⚠️ Alias alloy đã ngừng hoạt động — giọng Rachel mà nó trỏ tới đã bị ElevenLabs thu hồi. Gửi alloy vẫn ra audio nhưng là giọng mặc định của hệ thống, không phải Rachel. Hãy dùng nova (nữ) hoặc echo (nam) thay thế.

Cách 2 — Dùng voice_id trực tiếp (lấy từ bảng 12 giọng Việt ở trên, hoặc từ GET /v1/audio/voices):

{ "model": "elevenlabs/eleven_v3", "voice": "ArosID24mP18TEiQpNhs", "input": "Xin chào!" }

Cách 3 — Lấy danh sách voice qua API (kèm preview_url để nghe thử, server cache 1h):

curl https://platform.beeknoee.com/v1/audio/voices \
  -H "Authorization: Bearer sk-bee-your-key"

Response:

{
  "provider": "elevenlabs",
  "aliases": { "nova": "EXAVITQu4vr4xnSDxMaL", "echo": "JBFqnCBsd6RMkjVDRZzb" },
  "voices": [
    { "voice_id": "ArosID24mP18TEiQpNhs", "name": "Thien Trang - Vietnamese Northern Accent",
      "category": "professional",
      "labels": { "gender": "female", "accent": "northern", "language": "vi",
                  "use_case": "narrative_story" },
      "preview_url": "https://storage.googleapis.com/..." }
  ]
}

Lọc giọng Việt bằng labels.language === "vi", lọc theo vùng miền bằng labels.accent (northern / central / southern).

💡 speed hỗ trợ 0.7–1.2 (giá trị ngoài khoảng sẽ được clamp). Danh sách này là nguồn sự thật duy nhất về giọng dùng được — gửi voice_id ngoài danh sách sẽ nhận lỗi 400.

Ví dụ với alias:

{ "model": "elevenlabs/eleven_v3", "voice": "nova", "input": "Xin chào từ ElevenLabs!" }

Response

API trả về binary audio (không phải JSON), giống hệt OpenAI:

Lưu trực tiếp response body thành file audio.

Tải lại audio đã tạo

Mỗi lần tạo audio, hệ thống giữ lại file một thời gian để bạn tải lại mà không phải trả tiền lần nữa.

Cách nhanh nhất: vào trang Lịch sử sử dụng — dòng nào là TTS sẽ có nút tải màu hổ phách ngay cạnh tên model. Hết hạn lưu thì nút tự ẩn.

Hoặc gọi API:

curl https://platform.beeknoee.com/v1/audio/speech/{job_id}/download \
  -H "Authorization: Bearer $BEEKNOEE_API_KEY" \
  --output speech.mp3

Chỉ chủ sở hữu tải được — biết job_id của người khác cũng không lấy được file.

File rất lớn (trên 50MB) chỉ được ghi vào lịch sử chứ không giữ file, nên sẽ không có nút tải.

Ví dụ

1. Basic TTS — cURL

curl -X POST https://platform.beeknoee.com/v1/audio/speech \
  -H "Authorization: Bearer sk-bee-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/tts-1",
    "input": "Xin chào! Đây là giọng nói từ Beeknoee Platform.",
    "voice": "alloy"
  }' \
  --output speech.mp3

2. Google TTS Free (miễn phí) — cURL

curl -X POST https://platform.beeknoee.com/v1/audio/speech \
  -H "Authorization: Bearer sk-bee-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/google-tts",
    "input": "Xin chào! Đây là giọng Google Translate miễn phí.",
    "voice": "vi"
  }' \
  --output speech.mp3

2b. ElevenLabs — cURL (giọng Việt giống người thật nhất)

# Dùng chung endpoint /v1/audio/speech — không cần gọi api.elevenlabs.io
curl -X POST https://platform.beeknoee.com/v1/audio/speech \
  -H "Authorization: Bearer sk-bee-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "elevenlabs/eleven_v3",
    "input": "Xin chào! Đây là giọng nói ElevenLabs, tự nhiên như người thật.",
    "voice": "ArosID24mP18TEiQpNhs"
  }' \
  --output elevenlabs.mp3

ArosID24mP18TEiQpNhs = Thien Trang, nữ, giọng Bắc. Xem 12 giọng Việt để chọn giọng khác.

2c. ElevenLabs — Python với voice_id tùy chọn

from openai import OpenAI
from pathlib import Path

client = OpenAI(
    api_key="sk-bee-your-key",
    base_url="https://platform.beeknoee.com/v1"
)

# Bước 1: lấy danh sách voice + link nghe thử, lọc riêng giọng Việt
import httpx
voices = httpx.get(
    "https://platform.beeknoee.com/v1/audio/voices",
    headers={"Authorization": "Bearer sk-bee-your-key"},
).json()["voices"]

viet = [v for v in voices if v["labels"].get("language") == "vi"]
for v in viet:
    print(v["voice_id"], v["name"], v["labels"].get("accent"), v["preview_url"])

# Bước 2: TTS với voice_id đã chọn (hoặc dùng alias "nova"/"echo"...)
response = client.audio.speech.create(
    model="elevenlabs/eleven_v3",
    voice=viet[0]["voice_id"],
    input="Giọng đọc tiếng Việt tự nhiên, đúng dấu, đúng ngữ điệu.",
)

Path("elevenlabs_v3.mp3").write_bytes(response.content)

3. Python — OpenAI SDK

from openai import OpenAI
from pathlib import Path

client = OpenAI(
    api_key="sk-bee-your-key",
    base_url="https://platform.beeknoee.com/v1"
)

# OpenAI TTS-1 với giọng alloy
response = client.audio.speech.create(
    model="openai/tts-1",
    voice="alloy",
    input="Trí tuệ nhân tạo đang thay đổi thế giới.",
)

speech_file = Path("speech.mp3")
response.stream_to_file(speech_file)
print(f"Saved {speech_file} ({speech_file.stat().st_size} bytes)")

4. Python — Google TTS Free (miễn phí)

from openai import OpenAI
from pathlib import Path

client = OpenAI(
    api_key="sk-bee-your-key",
    base_url="https://platform.beeknoee.com/v1"
)

# Google TTS Free — miễn phí, dùng mã ngôn ngữ làm voice
response = client.audio.speech.create(
    model="google/google-tts",
    voice="vi",  # tiếng Việt
    input="Beeknoee là nền tảng AI proxy tốt nhất Việt Nam.",
)

Path("free_speech.mp3").write_bytes(response.content)
print("Saved free_speech.mp3!")

5. JavaScript / Node.js

import OpenAI from 'openai';
import { writeFileSync } from 'fs';

const client = new OpenAI({
  apiKey: 'sk-bee-your-key',
  baseURL: 'https://platform.beeknoee.com/v1',
});

const response = await client.audio.speech.create({
  model: 'openai/tts-1',
  voice: 'nova',
  input: 'Xin chào từ Beeknoee! Giọng nói tự nhiên, hỗ trợ tiếng Việt.',
});

const buffer = Buffer.from(await response.arrayBuffer());
writeFileSync('speech.mp3', buffer);
console.log(`Saved speech.mp3 (${buffer.length} bytes)`);

6. Google Cloud TTS (WaveNet) — Python

from openai import OpenAI
from pathlib import Path

client = OpenAI(
    api_key="sk-bee-your-key",
    base_url="https://platform.beeknoee.com/v1"
)

# Google Gemini TTS — voice là TÊN TRẦN (Kore), không có tiền tố ngôn ngữ
response = client.audio.speech.create(
    model="google/gemini-2.5-flash-tts",
    voice="Kore",
    input="Giọng Gemini tự nhiên, hỗ trợ tiếng Việt đầy đủ.",
)

Path("gemini_tts.mp3").write_bytes(response.content)

7. Tạo audiobook — đọc từng chương

from openai import OpenAI
from pathlib import Path

client = OpenAI(
    api_key="sk-bee-your-key",
    base_url="https://platform.beeknoee.com/v1"
)

chapters = [
    "Chương 1: Ngày xưa, trong một ngôi làng nhỏ bên bờ sông...",
    "Chương 2: Cô gái ấy lớn lên và trở thành một nhà khoa học...",
    "Chương 3: Phát minh của cô đã thay đổi cả thế giới...",
]

for i, chapter in enumerate(chapters):
    response = client.audio.speech.create(
        model="openai/tts-1-hd",       # Chất lượng cao cho audiobook
        voice="sage",           # Giọng điềm tĩnh, kể chuyện
        input=chapter,
        speed=0.9,              # Đọc chậm hơn một chút
    )
    path = Path(f"chapter_{i+1}.mp3")
    path.write_bytes(response.content)
    print(f"✅ {path} ({path.stat().st_size:,} bytes)")

8. TTS với speed control — cURL

# Đọc nhanh 1.5x
curl -X POST https://platform.beeknoee.com/v1/audio/speech \
  -H "Authorization: Bearer sk-bee-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/tts-1",
    "input": "Đây là bản đọc tốc độ 1.5x, nhanh hơn bình thường.",
    "voice": "echo",
    "speed": 1.5
  }' \
  --output fast_speech.mp3

9. Chọn định dạng audio — Opus cho voice chat

from openai import OpenAI

client = OpenAI(
    api_key="sk-bee-your-key",
    base_url="https://platform.beeknoee.com/v1"
)

# Opus — file nhỏ, lý tưởng cho voice chat / streaming
response = client.audio.speech.create(
    model="openai/gpt-4o-mini-tts",
    voice="coral",
    input="Opus format rất nhỏ gọn, phù hợp cho ứng dụng real-time.",
    response_format="opus",
)

with open("speech.opus", "wb") as f:
    f.write(response.content)

Rate Limits

Rate limit áp dụng theo plan người dùng, giống text model:

Model miễn phí

Model trả phí

Đây là mức mặc định theo gói. Một số model có giới hạn riêng cấu hình sẵn — mức riêng đó sẽ đè lên bảng trên. Xem GET /v1/models/tts để biết con số áp dụng cho từng model.

Khi vượt giới hạn, response 429 kèm header Retry-After (số giây nên chờ).

Chống tính tiền 2 lần (Idempotency)

Ví chỉ bị trừ sau khi nhà cung cấp trả audio. Nếu kết nối rớt ở đoạn giữa, bạn đã bị trừ tiền nhưng chưa nhận được file — gửi lại sẽ tính tiền lần nữa.

Để tránh, hệ thống nhớ mỗi request trong 60 giây. Trong khoảng đó, request giống hệt sẽ nhận lại đúng file cũ, không gọi nhà cung cấp và không trừ tiền lần hai.

Hai request được coi là giống hệt khi trùng cả model, voice, input, response_format và speed. Đổi bất kỳ thứ nào — kể cả thêm một dấu chấm vào input — là tạo bản mới ngay.

Tự chỉ định khoá

Gửi header Idempotency-Key để tự quyết định thế nào là "cùng một request":

curl https://platform.beeknoee.com/v1/audio/speech \
  -H "Authorization: Bearer $BEEKNOEE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: don-hang-12345" \
  -d '{"model":"elevenlabs/eleven_v3","input":"Xin chào","voice":"ArosID24mP18TEiQpNhs"}' \
  --output speech.mp3

Retry với cùng Idempotency-Key sẽ luôn nhận lại kết quả đầu tiên. Dùng key khác nhau cho các lần tạo khác nhau, kể cả khi nội dung trùng.

Muốn tạo lại cùng một câu để lấy bản đọc khác? ElevenLabs mỗi lần đọc cho ra bản hơi khác nhau. Gửi Idempotency-Key mới, đổi giọng, hoặc đợi qua 60 giây.

Mã lỗi liên quan

Billing — Cách tính phí

• Tính theo số ký tự (characters) trong input — đếm theo ký tự Unicode sau chuẩn hoá NFC: chữ Việt có dấu, emoji… mỗi cái tính 1 ký tự (dù gõ bằng bộ gõ tổ hợp dấu hay dựng sẵn)
• Trừ trực tiếp vào ví VNĐ
• Model google-tts hoàn toàn miễn phí

Công thức: Chi phí = (số ký tự / 1.000.000) × đơn giá của model

Đơn giá từng model xem tại Audio Models; số tiền thực tế của mỗi lần gọi nằm ở API Usage.

Error Handling

Đọc bảng này thế nào: 400 và 403 nghĩa là gửi lại y hệt cũng hỏng — phải sửa request. 429, 502, 500 là sự cố thoáng qua, gửi lại là hợp lý. SDK chính thức của OpenAI/Anthropic tự động retry đúng theo quy tắc này.

Gửi lại có bị tính tiền 2 lần không? Không, nếu trong 60 giây và request y hệt — xem Chống tính tiền 2 lần. Lỗi thì vốn đã không bị trừ tiền.

import time
from openai import OpenAI, RateLimitError

client = OpenAI(
    api_key="sk-bee-your-key",
    base_url="https://platform.beeknoee.com/v1"
)

def tts_with_retry(text, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = client.audio.speech.create(
                model="openai/tts-1",
                voice="alloy",
                input=text,
            )
            return response.content
        except RateLimitError:
            wait = 2 ** attempt
            print(f"Rate limited, waiting {wait}s...")
            time.sleep(wait)
    raise Exception("Max retries exceeded")

So sánh: Nên chọn model nào?

Xem danh sách models

curl https://platform.beeknoee.com/v1/models \
  -H "Authorization: Bearer sk-bee-your-key"

Best Practices

1. Chọn format phù hợp — mp3 cho download, opus cho streaming/voice chat, wav cho xử lý audio
2. Chia text dài — Tối đa 4,096–5,000 chars/request. Chia thành nhiều request cho văn bản dài
3. Cache audio — Lưu file audio, không cần tạo lại mỗi lần cho cùng nội dung
4. Dùng model miễn phí để test — google/google-tts miễn phí, lý tưởng để prototype trước khi chuyển sang model cao cấp
5. Speed control — Giảm speed xuống 0.8–0.9 cho audiobook, tăng 1.2–1.5 cho tóm tắt nhanh
6. Nghe thử voice trước — Dùng openai.fm cho OpenAI voices, geminitts.net cho Google voices
7. Voice selection — Test nhiều voices để chọn giọng phù hợp với nội dung

Tiếp theo

• Chat Completions — Kết hợp AI chat + TTS cho voice assistant
• Models — Xem tất cả text models khả dụng
• Embeddings — Tạo embeddings cho tìm kiếm ngữ nghĩa
• Image Generation — Tạo ảnh từ text
• API Usage — Theo dõi chi phí sử dụng