TokenLab

Âm thanh & thời gian thực

Tạo bản ghi âm (Transcription)

Chuyển đổi âm thanh thành văn bản theo ngôn ngữ đầu vào

POST
/v1/audio/transcriptions

Sử dụng GET /v1/models?recommended_for=stt để lấy các mô hình chuyển đổi âm thanh hiện tại.

Phần thân yêu cầu (Request Body)

Quá trình chuyển đổi âm thanh có thể trả về kết quả ngay lập tức hoặc chấp nhận một tác vụ bất đồng bộ với mã HTTP 200, id và status. Đối với tác vụ đã được chấp nhận, hãy thực hiện polling (truy vấn định kỳ) GET /v1/tasks/{id} với id được trả về. Đối với các tệp âm thanh đồng bộ dài hơn, hãy cho phép thời gian chờ (timeout) của client ít nhất là 120s.

filefilebắt buộc

Tệp âm thanh cần chuyển đổi. Các định dạng được hỗ trợ: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm. Kích thước tệp tối đa: 25 MB.

modelstringbắt buộc

ID của mô hình chuyển đổi âm thanh, ví dụ whisper-large-v3 hoặc qwen3-asr-flash. Tìm các lựa chọn hiện tại với GET /v1/models?recommended_for=stt. Không có mô hình mặc định.

languagestring

Ngôn ngữ của âm thanh theo định dạng ISO-639-1 (ví dụ: en, zh, ja).

promptstring

Văn bản tùy chọn để hướng dẫn phong cách của mô hình hoặc tiếp nối một phân đoạn trước đó, dành cho các mô hình liệt kê tham số này, chẳng hạn như qwen3-asr-flash.

response_formatstringmặc định: json

Định dạng đầu ra. Các mô hình khác nhau sẽ có sự khác biệt: tất cả đều chấp nhận json, và một số mô hình cũng liệt kê text hoặc verbose_json. Hãy kiểm tra chi tiết của mô hình đã chọn trước khi gửi một giá trị khác. text trả về văn bản thô thay vì một đối tượng JSON.

temperaturenumber

Nhiệt độ lấy mẫu (sampling temperature) từ 0 đến 1, chỉ dành cho các mô hình liệt kê tham số này.

timestamp_granularitiesarray

word và/hoặc segment, chỉ dành cho các mô hình liệt kê tham số này. Một số mô hình cần response_format=verbose_json để có dấu thời gian (timestamps). Trong các yêu cầu multipart, hãy lặp lại timestamp_granularities[] cho nhiều giá trị.

Phản hồi (Response)

Các trường dưới đây mô tả các phản hồi JSON cho việc chuyển đổi âm thanh hoặc dịch thuật. text, srt, và vtt trả về văn bản thô hoặc phụ đề thay vì một đối tượng JSON. Các trường bổ sung phụ thuộc vào mô hình và định dạng đầu ra.

textstring

Văn bản đã được chuyển đổi.

Đối với verbose_json:

taskstring

Tên tác vụ khi được trả về, chẳng hạn như transcribe.

languagestring

Ngôn ngữ được phát hiện.

durationnumber

Thời lượng âm thanh tính bằng giây.

segmentsarray

Các phân đoạn chuyển đổi âm thanh kèm theo dấu thời gian.

wordsarray

Dấu thời gian ở cấp độ từ (nếu được yêu cầu).

Một tác vụ chuyển đổi âm thanh bất đồng bộ được chấp nhận sẽ trả về các trường sau thay vì bản ghi âm. Hãy thực hiện polling GET /v1/tasks/{id}; một tác vụ đã hoàn thành sẽ trả về text và, khi có sẵn, sẽ trả về duration, segments, và words.

idstring

ID của tác vụ.

task_idstring

Bí danh định danh tác vụ bất đồng bộ khi được cung cấp.

statusstring

Trạng thái tác vụ: pending, processing, completed, hoặc failed.

poll_urlstring

URL trạng thái cho tác vụ này. Hãy thực hiện polling GET /v1/tasks/{id} với id.

Yêu cầu

curl -X POST "https://api.tokenlab.sh/v1/audio/transcriptions" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F file="@audio.mp3" \
  -F model="whisper-large-v3" \
  -F language="en"

Phản hồi

{
  "text": "Hello, this is a test of the transcription API."
}

Xác thực

BearerAuth
AuthorizationBearer <token>

Xác thực bằng Khóa API. Tạo hoặc quản lý khóa API trong Dashboard > API > API Keys.

Vị trí: header

Header

X-TokenLab-Delivery-Policy?string

Chính sách phân phối theo yêu cầu. Ghi đè các mặc định của API key và Workspace. Tự động thử TokenLab Verified trước và có thể chuyển đổi một lần sang Official chỉ trước khi xuất, chấp nhận yêu cầu hoặc tạo tài nguyên cố định.

Giá trị hợp lệ

  • "auto"
  • "verified"
  • "official"

Nội dung yêu cầu

multipart/form-data

Phản hồi

application/json

application/json

application/json

application/json

application/json

application/json