Text-to-Speech

Trạm AI hỗ trợ text-to-speech (TTS) thông qua endpoint chuyên dụng /v1/audio/speech, tương thích với OpenAI Audio Speech API. Người dùng gửi văn bản và nhận về một byte stream âm thanh thô ở định dạng được lựa chọn.

Khám phá model

Người dùng có thể tìm các model TTS theo nhiều cách:

Qua API

Dùng Public Models API để lấy danh sách model, sau đó lọc các model có mode là "audio_speech":

$
# Lấy danh sách tất cả model
$
curl "https://api.staging.tram.ai.vn/public/models"
$
$
# Tìm model TTS: lọc các model có mode = "audio_speech"

Trên trang Models

Truy cập trang Models và lọc theo output modalities để tìm các model có khả năng tổng hợp giọng nói. Hãy tìm model nào có liệt kê "speech" trong output modalities.

Sử dụng API

Gửi một request POST tới /v1/audio/speech kèm văn bản cần tổng hợp. Response trả về là một byte stream âm thanh thô — không phải JSON — nên người dùng có thể đưa thẳng nó vào một file hoặc trình phát âm thanh.

Ví dụ cơ bản

1
import OpenAI from 'openai';
2
import fs from 'fs';
3
4
const openai = new OpenAI({
5
  baseURL: 'https://api.staging.tram.ai.vn/v1',
6
  apiKey: '<TRAM_AI_API_KEY>',
7
});
8
9
const response = await openai.audio.speech.create({
10
  model: 'openai/gpt-4o-mini-tts-2025-12-15',
11
  input: 'Hello! This is a text-to-speech test.',
12
  voice: 'alloy',
13
  response_format: 'mp3',
14
});
15
16
// Save the audio response to a file
17
const buffer = Buffer.from(await response.arrayBuffer());
18
await fs.promises.writeFile('output.mp3', buffer);
19
console.log('Audio saved to output.mp3');

Tham số request

Tùy chọn riêng theo provider

Người dùng có thể truyền các tùy chọn riêng theo provider bằng tham số provider. Tùy chọn được nhóm theo khóa là slug của provider, và chỉ tùy chọn của provider khớp mới được chuyển tiếp:

1
{
2
  "model": "openai/gpt-4o-mini-tts-2025-12-15",
3
  "input": "Hello world",
4
  "voice": "alloy",
5
  "provider": {
6
    "options": {
7
      "openai": {
8
        "instructions": "Speak in a warm, friendly tone."
9
      }
10
    }
11
  }
12
}

Định dạng response

Endpoint TTS trả về một byte stream âm thanh thô, không phải JSON. Response sẽ kèm theo các header sau:

Định dạng đầu ra

Giá

Các model TTS được tính giá theo từng ký tự của văn bản đầu vào. Mức giá khác nhau tùy model và provider. Người dùng có thể xem chi phí trên mỗi ký tự của từng model trên trang Models hoặc qua Models API.

Tương thích với OpenAI SDK

Endpoint TTS hoàn toàn tương thích với OpenAI SDK. Người dùng có thể dùng thư viện client của OpenAI bằng cách trỏ chúng tới base URL của Trạm AI:

1
from openai import OpenAI
2
3
client = OpenAI(
4
  base_url="https://api.staging.tram.ai.vn/v1",
5
  api_key="<TRAM_AI_API_KEY>",
6
)
7
8
# Non-streaming: get the full audio response
9
response = client.audio.speech.create(
10
  model="openai/gpt-4o-mini-tts-2025-12-15",
11
  input="The quick brown fox jumps over the lazy dog.",
12
  voice="nova",
13
  response_format="mp3"
14
)
15
response.write_to_file("output.mp3")
16
17
# Streaming: process audio chunks as they arrive
18
with client.audio.speech.with_streaming_response.create(
19
  model="openai/gpt-4o-mini-tts-2025-12-15",
20
  input="The quick brown fox jumps over the lazy dog.",
21
  voice="nova",
22
  response_format="mp3"
23
) as response:
24
  response.stream_to_file("output.mp3")

Thực hành tốt nhất

• Chọn đúng định dạng: Dùng mp3 để lưu trữ và phát lại thông thường. Dùng pcm cho các pipeline streaming thời gian thực, nơi độ trễ là yếu tố quan trọng
• Lựa chọn giọng nói: Mỗi provider cung cấp một bộ giọng khác nhau. Hãy xem tài liệu của model hoặc thử qua các giọng khả dụng để tìm giọng phù hợp nhất.
• Độ dài đầu vào: Với những văn bản rất dài, hãy cân nhắc chia đầu vào thành các đoạn nhỏ hơn rồi nối các đoạn âm thanh đầu ra lại. Cách này giúp cải thiện độ tin cậy và giảm độ trễ cho đoạn âm thanh đầu tiên
• Tham số speed: Tham số speed chỉ được một số provider hỗ trợ (ví dụ: OpenAI). Các provider không hỗ trợ sẽ âm thầm bỏ qua tham số này

Khắc phục sự cố

File âm thanh trống hoặc bị hỏng?

• Kiểm tra response_format có khớp với cách lưu file hay không (ví dụ: đừng lưu đầu ra pcm với phần mở rộng .mp3)
• Kiểm tra mã trạng thái của response — response không phải 200 sẽ trả về phần thân lỗi dạng JSON chứ không phải âm thanh

Không tìm thấy model?

• Dùng trang Models để tìm các model TTS khả dụng
• Kiểm tra slug của model có chính xác hay không (ví dụ: openai/gpt-4o-mini-tts-2025-12-15, không phải gpt-4o-mini-tts)

Giọng nói không khả dụng?

• Các giọng khả dụng khác nhau tùy provider. Hãy xem tài liệu của provider để biết các định danh giọng nói được hỗ trợ
• Mỗi model đều có bộ giọng riêng — hãy xem trang của model trên trang Models để biết danh sách đầy đủ