🎤 Speech-to-Text API

Chuyển audio thành văn bản (transcription) với hơn 20 model từ OpenAI, Groq, Google, AssemblyAI, Deepgram, NVIDIA, Mistral, Qwen 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.

ℹ️ ElevenLabs Scribe (cập nhật 08/10/2026): có elevenlabs/scribe-v2 và elevenlabs/scribe-v2-medical trong nhóm đa hãng — theo luật của nhóm đó (không srt/vtt, không /v1/audio/translations). ID gạch dưới scribe_v2 không gọi được — gọi vào sẽ báo model không tồn tại. Chép tiếng Việt bằng Scribe chưa được Beeknoee thử.

STT hiện dùng được: OpenAI (whisper-1, gpt-4o-transcribe, gpt-4o-mini-transcribe), Groq (whisper-large-v3, whisper-large-v3-turbo), Google (google/gemini-2.5-flash-stt, google/gemini-2.5-flash-lite-stt, google/gemini-2.5-pro-stt) và nhóm model đa hãng (AssemblyAI, Deepgram, NVIDIA, Mistral, Qwen, Fish Audio, Grok…). Danh sách chuẩn xác xem tại trang Audio Models.

Endpoint

POST https://platform.beeknoee.com/v1/audio/transcriptions
POST https://platform.beeknoee.com/v1/audio/translations

• Transcriptions: Chuyển audio → text (giữ nguyên ngôn ngữ gốc)
• Translations: Chuyển audio → text tiếng Anh (dịch sang English)

💡 Mọi provider dùng chung endpoint này. Bạn KHÔNG cần gọi API gốc của từng nhà cung cấp: hệ thống tự chuyển request sang đúng nơi và trả kết quả về đúng format OpenAI. Chỉ cần đổi model là xong.

⚠️ Riêng Translations chỉ hỗ trợ model OpenAI và Groq — dùng whisper-1 hoặc gpt-4o-transcribe để dịch.

Request

Headers

⚠️ Không cần Content-Type header — browser/client tự set multipart/form-data với boundary khi upload file.

Body Parameters (multipart/form-data)

⚠️ Lưu ý format compatibility:

• Model gpt-4o-transcribe và gpt-4o-mini-transcribe chỉ hỗ trợ json và text. Hệ thống sẽ tự động chuyển verbose_json → json, srt/vtt → text nếu gửi format không tương thích.

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.

OpenAI Models

Groq Models (Ultra Fast)

Model đa hãng (từ 03/10/2026)

Thêm model chép lời của nhiều hãng (ví dụ AssemblyAI, Deepgram, NVIDIA, Mistral, Qwen…) — danh sách và giá xem tại Audio Models, mục STT.

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

• response_format: chỉ json, verbose_json, text. Gửi srt / vtt ⇒ lỗi 400, không trừ tiền.
• Không hỗ trợ /v1/audio/translations (dịch sang tiếng Anh) — dùng whisper-1 cho việc đó.
• Không gửi language ⇒ model tự nhận diện ngôn ngữ.
• File tối đa 25 MB. Một số model chỉ nhận vài định dạng audio (vd chỉ wav) — định dạng không hỗ trợ ⇒ lỗi 400, không trừ tiền.
• AssemblyAI Universal-3.5 Pro: mỗi file tối đa 120 giây.
• Model không có verbose_json riêng ⇒ Beeknoee vẫn trả verbose_json có text (không có segments / words).

Tiếng Việt — Beeknoee đã thử từng model bằng file tiếng Việt thật (rê chuột vào ô Ngôn ngữ trên thẻ model để xem nhanh):

💡 Khuyến nghị: Dùng gpt-4o-mini-transcribe nếu cần giá rẻ + chất lượng tốt. Dùng whisper-large-v3-turbo (Groq) nếu cần tốc độ nhanh nhất. Dùng whisper-1 nếu cần SRT/VTT subtitles.

Response

JSON response (default)

{
  "text": "Xin chào, đây là bản ghi âm test.",
  "task": "transcribe",
  "language": "vi",
  "duration": 5.2
}

Verbose JSON response (response_format=verbose_json)

{
  "text": "Xin chào, đây là bản ghi âm test.",
  "task": "transcribe",
  "language": "vi",
  "duration": 5.2,
  "segments": [
    {
      "id": 0,
      "start": 0.0,
      "end": 2.5,
      "text": "Xin chào,"
    },
    {
      "id": 1,
      "start": 2.5,
      "end": 5.2,
      "text": " đây là bản ghi âm test."
    }
  ]
}

SRT response (response_format=srt)

1
00:00:00,000 --> 00:00:02,500
Xin chào,

2
00:00:02,500 --> 00:00:05,200
đây là bản ghi âm test.

VTT response (response_format=vtt)

WEBVTT

00:00:00.000 --> 00:00:02.500
Xin chào,

00:00:02.500 --> 00:00:05.200
đây là bản ghi âm test.

Ví dụ

1. Basic Transcription — cURL

curl -X POST https://platform.beeknoee.com/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-bee-your-key" \
  -F [email protected] \
  -F model=whisper-1

2. Transcribe tiếng Việt — cURL

curl -X POST https://platform.beeknoee.com/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-bee-your-key" \
  -F [email protected] \
  -F model=gpt-4o-mini-transcribe \
  -F language=vi

3. Tạo SRT subtitles — cURL

curl -X POST https://platform.beeknoee.com/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-bee-your-key" \
  -F [email protected] \
  -F model=whisper-1 \
  -F response_format=srt \
  --output subtitles.srt

4. Python — OpenAI SDK

from openai import OpenAI

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

# Transcribe audio file
audio_file = open("recording.mp3", "rb")
transcript = client.audio.transcriptions.create(
    model="gpt-4o-mini-transcribe",
    file=audio_file,
    language="vi",
)

print(transcript.text)

5. Python — Groq Ultra Fast

from openai import OpenAI

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

# Groq Whisper — transcribe cực nhanh
audio_file = open("long-meeting.mp3", "rb")
transcript = client.audio.transcriptions.create(
    model="whisper-large-v3-turbo",
    file=audio_file,
)

print(f"Duration: {transcript.duration}s")
print(f"Text: {transcript.text}")

6. Python — Tạo subtitles SRT

from openai import OpenAI
from pathlib import Path

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

audio_file = open("video.mp3", "rb")
transcript = client.audio.transcriptions.create(
    model="whisper-1",
    file=audio_file,
    response_format="srt",
)

Path("subtitles.srt").write_text(transcript)
print("Saved subtitles.srt!")

7. JavaScript / Node.js

import OpenAI from 'openai';
import fs from 'fs';

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

const transcript = await client.audio.transcriptions.create({
  model: 'gpt-4o-mini-transcribe',
  file: fs.createReadStream('recording.mp3'),
  language: 'vi',
});

console.log(transcript.text);

8. Dịch audio sang tiếng Anh — Translation

from openai import OpenAI

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

# Translate: audio tiếng Việt → text tiếng Anh
audio_file = open("tieng-viet.mp3", "rb")
translation = client.audio.translations.create(
    model="whisper-1",
    file=audio_file,
)

print(translation.text)  # English text

9. Batch transcribe nhiều file

from openai import OpenAI
from pathlib import Path

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

audio_files = list(Path("recordings/").glob("*.mp3"))

for audio_path in audio_files:
    with open(audio_path, "rb") as f:
        transcript = client.audio.transcriptions.create(
            model="whisper-large-v3-turbo",  # Groq = nhanh nhất
            file=f,
            language="vi",
        )
    
    # Save text
    txt_path = audio_path.with_suffix(".txt")
    txt_path.write_text(transcript.text)
    print(f"✅ {audio_path.name} → {len(transcript.text)} chars")

Ngôn ngữ hỗ trợ

Whisper và Groq hỗ trợ 99+ ngôn ngữ. Một số phổ biến:

💡 Tip: Chỉ định language giúp model nhận diện chính xác hơn, đặc biệt với audio ngắn hoặc có nhiều ngôn ngữ.

File audio hỗ trợ

⚠️ Tối đa 25MB per file. Nếu file lớn hơn, hãy chia nhỏ hoặc nén sang MP3 trước.

Rate Limits

Rate limit áp dụng theo plan người dùng, giống text model. Model STT hiện đều là model trả phí:

Nếu về sau có model STT miễn phí, mức áp dụng là 10 / 20 / 40 / 60 RPM kèm 250 / 1,500 / 3,000 / 5,000 RPD theo bốn gói trên.

Đâ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.

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)

STT tính tiền theo phút audio, và upload file lớn thì rớt mạng là chuyện thường — SDK OpenAI còn tự retry. Mỗi lần retry là một lần trả tiền cho cùng một file.

Hệ thống nhớ mỗi request trong 60 giây. Trong khoảng đó, request giống hệt nhận lại đúng kết quả 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 nội dung file (băm sha256, không phải tên hay dung lượng) cùng với model, language, response_format, prompt và temperature.

Tự chỉ định khoá

curl https://platform.beeknoee.com/v1/audio/transcriptions \
  -H "Authorization: Bearer $BEEKNOEE_API_KEY" \
  -H "Idempotency-Key: cuoc-hop-2026-07-26" \
  -F [email protected] \
  -F model=whisper-1

Retry với cùng Idempotency-Key luôn nhận lại kết quả đầu tiên.

Mã lỗi liên quan

Billing — Cách tính phí

• Tính theo thời lượng audio thật — không phải file size. Thứ tự lấy số giây (từ 03/10/2026): số giây do nhà cung cấp báo → duration của verbose_json → đọc từ header file WAV (chính xác) → chỉ khi không có cách nào khác mới ước lượng theo dung lượng file
• Trừ trực tiếp vào ví VNĐ
• Hệ thống tạm giữ số dư theo ước tính trước khi chép, rồi trừ đúng số tiền sau khi có kết quả

💡 Muốn hoá đơn khớp tuyệt đối với thời lượng: gửi file WAV, hoặc dùng model trả số giây (vd whisper-1).

Công thức:

Chi phí = số phút audio × đơn giá của model

Đơn giá từng model xem tại Audio Models.

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à cùng file + cùng tham số — 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 transcribe_with_retry(file_path, max_retries=3):
    for attempt in range(max_retries):
        try:
            with open(file_path, "rb") as f:
                transcript = client.audio.transcriptions.create(
                    model="gpt-4o-mini-transcribe",
                    file=f,
                    language="vi",
                )
            return transcript.text
        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"

💡 Lọc theo modelType: "STT" trong kết quả để xem riêng các model speech-to-text.

Best Practices

1. Chỉ định ngôn ngữ — Set language giúp nhận diện chính xác hơn, đặc biệt audio ngắn
2. Dùng prompt context — VD: prompt="Beeknoee, AI Proxy, OpenAI" giúp model nhận đúng tên riêng
3. Nén file trước — Convert sang MP3 128kbps để giảm file size, không ảnh hưởng chất lượng transcription
4. Chia file dài — File >20 phút nên chia thành segments nhỏ, transcribe song song
5. Chọn format phù hợp — json cho app, text cho copy nhanh, srt/vtt cho subtitles
6. Groq cho tốc độ — Groq Whisper nhanh hơn OpenAI 5-10x, lý tưởng cho real-time
7. Retry logic — Luôn handle rate limit errors với exponential backoff

Tiếp theo

• Text-to-Speech — Kết hợp STT + TTS cho voice assistant
• Chat Completions — Dùng text transcribed để chat với AI
• Models — Xem tất cả text models khả dụng
• API Usage — Theo dõi chi phí sử dụng