Speech-to-Text

Trạm AI hỗ trợ speech-to-text (STT) qua một endpoint chuyên dụng /v1/audio/transcriptions. Người dùng gửi âm thanh đã mã hóa base64 và nhận về một response JSON gồm văn bản đã chuyển cùng thống kê sử dụng.

Tìm kiếm model

Có thể tìm các model STT 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à "transcription":

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

Trên trang Models

Truy cập trang Models rồi lọc theo output modality để tìm các model có khả năng transcribe âm thanh. Bạn cũng có thể duyệt bộ sưu tập Speech-to-Text để xem một danh sách được chọn lọc sẵn.

Sử dụng API

Gửi một request POST đến /v1/audio/transcriptions với body JSON chứa âm thanh đã mã hóa base64. Response trả về là JSON gồm văn bản đã chuyển và thống kê sử dụng tùy chọn.

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 audioBuffer = await fs.promises.readFile('audio.wav');
10
const base64Audio = audioBuffer.toString('base64');
11
12
const result = await fetch('https://api.staging.tram.ai.vn/v1/audio/transcriptions', {
13
  method: 'POST',
14
  headers: {
15
    Authorization: `Bearer <TRAM_AI_API_KEY>`,
16
    'Content-Type': 'application/json',
17
  },
18
  body: JSON.stringify({
19
    model: 'openai/whisper-1',
20
    input_audio: {
21
      data: base64Audio,
22
      format: 'wav',
23
    },
24
  }),
25
});
26
27
const data = await result.json();
28
console.log(data.text);

Tham số request

Tùy chọn riêng cho provider

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

1
{
2
  "model": "openai/whisper-large-v3",
3
  "input_audio": {
4
    "data": "UklGRiQA...",
5
    "format": "wav"
6
  },
7
  "provider": {
8
    "options": {
9
      "groq": {
10
        "prompt": "Expected vocabulary: Tram AI, API, transcription"
11
      }
12
    }
13
  }
14
}

Định dạng response

Endpoint STT trả về một response JSON chứa văn bản đã chuyển:

1
{
2
  "text": "Hello, this is a test of speech-to-text transcription.",
3
  "usage": {
4
    "seconds": 9.2,
5
    "total_tokens": 113,
6
    "input_tokens": 83,
7
    "output_tokens": 30,
8
    "cost": 0.000508
9
  }
10
}

Trường trong response

Response header

Định dạng âm thanh được hỗ trợ

Các định dạng âm thanh được hỗ trợ khác nhau tùy provider. Một số định dạng phổ biến gồm:

Định giá

Các model STT áp dụng những cách định giá khác nhau tùy theo provider:

• Theo thời lượng (ví dụ: OpenAI Whisper): Tính phí theo mỗi giây âm thanh đầu vào
• Theo token (ví dụ: các model OpenAI mới hơn): Tính phí theo mỗi input/output token, tương tự các model văn bản

Người dùng có thể xem chi phí của từng model trên trang Models hoặc qua Models API. Trường usage.cost trong response cho biết chi phí thực tế của mỗi request.

BYOK (Bring Your Own Key)

STT hỗ trợ BYOK, cho phép dùng chính API key của provider đang có. Khi đã cấu hình, request sẽ được route thẳng đến provider bằng key của người dùng, và Trạm AI chỉ tính phí nền tảng thay vì chi phí model theo mức sử dụng.

Playground

Hãy thử nghiệm các model STT ngay trên trình duyệt bằng Trạm AI Chat. Mở trang của bất kỳ model STT nào, rồi tải lên một file âm thanh và xem kết quả transcribe.

Khác biệt so với Audio Input

Trạm AI hỗ trợ hai cách xử lý âm thanh:

1. Speech-to-Text (trang này): Một endpoint chuyên dụng /v1/audio/transcriptions được tối ưu riêng cho việc transcribe. Endpoint này trả về JSON có cấu trúc gồm văn bản đã chuyển và dữ liệu sử dụng. Phù hợp nhất để chuyển âm thanh thành văn bản.
2. Audio input qua Chat Completions (tài liệu Audio): Gửi âm thanh như một phần của request /v1/chat/completions với content type input_audio. Model sẽ xử lý âm thanh cùng với văn bản và trả lời theo dạng hội thoại. Phù hợp nhất để phân tích âm thanh, trả lời câu hỏi về nội dung âm thanh, hoặc kết hợp âm thanh với các modality khác.

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

• Chọn đúng định dạng: WAV cho chất lượng tốt nhất khi transcribe. MP3 và các định dạng nén khác hoạt động tốt nhưng có thể giảm nhẹ độ chính xác với những đoạn âm thanh khó nghe
• Kích thước file: Với các file âm thanh rất dài, hãy cân nhắc chia nhỏ thành nhiều đoạn. Giới hạn timeout phía provider là 60 giây, nên các file quá lớn có thể bị timeout
• Mã hóa base64: Âm thanh phải được gửi dưới dạng dữ liệu mã hóa base64 (raw bytes, không phải data URI). Hầu hết các ngôn ngữ lập trình đều có sẵn công cụ để mã hóa base64

Khắc phục sự cố

Transcription rỗng hoặc không chính xác?

• Kiểm tra xem định dạng âm thanh có khớp với trường format trong request không
• Đảm bảo chất lượng âm thanh đủ tốt để transcribe

Request bị timeout?

• Các file âm thanh lớn có thể vượt quá giới hạn timeout 60 giây. Hãy chia các bản ghi dài thành nhiều đoạn nhỏ hơn
• Các định dạng nén (MP3, AAC) tạo ra payload nhỏ hơn và truyền nhanh hơn

Không tìm thấy model?

• Dùng trang Models hoặc Public Models API để tìm các model STT khả dụng (lọc theo mode: "transcription")
• Kiểm tra xem model slug có chính xác không (ví dụ: openai/whisper-1, không phải whisper-1)

Lỗi xác thực?

• Hãy đảm bảo API key đang dùng là hợp lệ từ dashboard Trạm AI
• Endpoint STT dùng cùng cơ chế xác thực với Chat Completions API