Chuyển giọng nói thành văn bản

RouteAPI cung cấp hai endpoint âm thanh của OpenAI: phiên âm trả về văn bản theo ngôn ngữ gốc, còn dịch luôn trả về tiếng Anh. Cả hai nhận multipart/form-data, trả kết quả trong cùng phản hồi — không có tác vụ bất đồng bộ hay bước thăm dò — và xác thực bằng cùng API Key như phần còn lại của API mô hình.

Endpoint	Mục đích	Phản hồi
`POST /v1/audio/transcriptions`	Âm thanh thành văn bản, theo ngôn ngữ gốc	JSON hoặc text, tùy theo `response_format`
`POST /v1/audio/translations`	Âm thanh thành văn bản tiếng Anh	JSON hoặc text, tùy theo `response_format`

Nếu Base URL của client được cấu hình không kèm /v1, POST /audio/transcriptions và POST /audio/translations cũng dùng được; gateway tự viết lại chúng thành đường dẫn /v1 ở bên trong.

Phiên âm

Phiên âm tệp âm thanh theo ngôn ngữ gốc. Gửi dưới dạng multipart/form-data.

POST /v1/audio/transcriptions

https://api.routeapi.ai/v1/audio/transcriptions

Tham số yêu cầu

Trường	Kiểu	Bắt buộc	Mô tả
`file`	file	Có	Tệp âm thanh. Chỉ phần `file` đầu tiên được chuyển tiếp
`model`	string	Có	ID mô hình phiên âm, ví dụ `whisper-1`, `gpt-4o-transcribe` hoặc `gpt-4o-mini-transcribe`
`response_format`	string	Không	Định dạng đầu ra mong muốn, ví dụ `json`, `text`, `srt`, `vtt` hoặc `verbose_json`. RouteAPI ghi nhận `json` là mặc định nhưng không ghi giá trị mặc định vào form được chuyển tiếp — khi bỏ trường này, upstream áp dụng mặc định của chính nó và body upstream được trả về nguyên vẹn
`language`	string	Không	Gợi ý ngôn ngữ theo ISO-639-1, được chuyển tiếp tới upstream
`prompt`	string	Không	Gợi ý ngữ cảnh/thuật ngữ, được chuyển tiếp tới upstream
`temperature`	number	Không	Nhiệt độ lấy mẫu, được chuyển tiếp tới upstream
`timestamp_granularities[]`	array	Không	Mức chi tiết mốc thời gian; được chuyển tiếp và chỉ có ý nghĩa khi đi kèm `verbose_json` ở upstream

Các trường form khác cũng được chuyển tiếp. Gateway dựng lại body multipart từ form của bạn: nó tự ghi model, sao chép phần tệp đầu tiên và chuyển tiếp mọi trường văn bản còn lại. RouteAPI chỉ kiểm tra model; việc các trường như chunking_strategy có được áp dụng hay không do mô hình upstream quyết định.

Ví dụ

curl https://api.routeapi.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -F "file=@./meeting.mp3" \
  -F "model=whisper-1" \
  -F "response_format=json" \
  -F "language=en"

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ROUTEAPI_KEY"],
    base_url="https://api.routeapi.ai/v1",
)

with open("meeting.mp3", "rb") as audio_file:
    transcript = client.audio.transcriptions.create(
        model="whisper-1",
        file=audio_file,
        response_format="json",
    )

print(transcript.text)

Phản hồi

Body phản hồi của upstream được trả về nguyên vẹn, với Content-Type và Content-Length được chuẩn hóa. Khi response_format là json — mặc định của upstream tương thích OpenAI — bạn nhận được:

{
  "text": "This is the transcribed content of the uploaded audio."
}

Với verbose_json, bạn thường còn nhận được task, language, duration và segments; với text, srt hoặc vtt, body là văn bản thuần thay vì JSON. Việc một mô hình cụ thể hỗ trợ chính xác những mục nào do nhà cung cấp quy định — RouteAPI không thay đổi hình dạng body.

Dịch âm thanh

Cùng cấu trúc multipart như phiên âm, nhưng đầu ra luôn là văn bản tiếng Anh, bất kể ngôn ngữ đầu vào. Các trường áp dụng như nhau (file, model, response_format, prompt, temperature). Ngôn ngữ gốc do mô hình tự nhận diện, nên hợp đồng của dịch không có tham số language — gateway vẫn chuyển tiếp các trường form bổ sung, nhưng upstream không chấp nhận chúng có thể từ chối yêu cầu.

POST /v1/audio/translations

https://api.routeapi.ai/v1/audio/translations

curl https://api.routeapi.ai/v1/audio/translations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -F "file=@./interview-de.mp3" \
  -F "model=whisper-1"

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ROUTEAPI_KEY"],
    base_url="https://api.routeapi.ai/v1",
)

with open("interview-de.mp3", "rb") as audio_file:
    result = client.audio.translations.create(
        model="whisper-1",
        file=audio_file,
    )

print(result.text)

Tính phí

Các lần gọi chuyển giọng nói thành văn bản dùng cùng cơ chế ví và quota như mọi lần gọi API mô hình khác: một khoản ước tính được tạm giữ trước, yêu cầu được quyết toán sau khi upstream phản hồi, và yêu cầu thất bại được hoàn lại. Giá lấy từ cấu hình của mô hình — xem Giá mô hình để biết giá được hiển thị thế nào trên trang chi tiết mô hình.

Nếu phản hồi upstream có đối tượng usage với total_tokens khác 0, mức sử dụng đó là căn cứ tính phí (input_tokens/output_tokens được dùng khi không có prompt_tokens/completion_tokens).
Nếu upstream không báo mức sử dụng, gateway dự phòng theo ước tính thời lượng: 1000 token mỗi phút âm thanh được tải lên và không có token đầu ra. Với các mô hình tính giá theo token, cùng ước tính này quyết định khoản tạm giữ (không thấp hơn mức tạm giữ tối thiểu của gateway cho mọi yêu cầu).
Nếu mức sử dụng được báo có chi tiết token âm thanh, các token đó được tính theo giá âm thanh; nếu không, chúng được tính như token đầu vào thông thường theo hệ số của mô hình. Bản dự phòng theo thời lượng không có chi tiết âm thanh, đó là lý do 1000 token mỗi phút khớp với mức giá theo phút.
Khi áp dụng bản dự phòng, chi phí phiên âm bám theo độ dài âm thanh chứ không theo lượng văn bản trả về. Khi upstream thực sự báo mức sử dụng, phân tích được báo đó sẽ được ưu tiên.

Lỗi

Yêu cầu âm thanh dùng body chuẩn { "error": { ... } }, và thông báo có kèm request ID để bạn tra trong nhật ký console. Xem Lỗi thường gặp để biết danh sách đầy đủ.

Mã trạng thái	Mã lỗi	Nguyên nhân
400	`invalid_request`	`model` bị thiếu hoặc rỗng (`Missing required field: model`)
403	`insufficient_user_quota` / `pre_consume_token_quota_failed`	Số dư tài khoản hoặc quota của Key không đủ cho chi phí ước tính
403	—	Mô hình nằm ngoài danh sách trắng mô hình của Key (`This token has no access to model ...`)
429	—	Vượt quá giới hạn tốc độ yêu cầu
503	`model_not_found`	Không có kênh khả dụng cho mô hình (`No valid upstream service`)
500	`count_token_failed`	Không đo được thời lượng âm thanh được tải lên (phần mở rộng hoặc định dạng chứa không được hỗ trợ)
500	`convert_request_failed`	Không thể chuyển đổi yêu cầu cho kênh — ví dụ phiên âm không có phần `file`, hoặc kênh có bộ chuyển đổi chưa triển khai âm thanh
4xx / 5xx	Mã lỗi của upstream	Nhà cung cấp từ chối yêu cầu; mã trạng thái và thông báo được chuyển tiếp nguyên vẹn

{
  "error": {
    "message": "Missing required field: model (request id: 20261023153000123456789AbCdEfGh)",
    "type": "error",
    "code": "invalid_request"
  }
}

Có hai kiểu lỗi bạn nên lường trước, vì chúng dễ bị nhầm là sự cố phía nhà cung cấp:

Thiếu file trong phiên âm hoặc dịch không bị tầng kiểm tra của gateway chặn; nó xuất hiện muộn hơn dưới dạng convert_request_failed. Hãy kiểm tra tên trường đúng là file và client thực sự đã đính kèm phần tương ứng.
Định dạng chứa âm thanh không được hỗ trợ thất bại ngay ở bước ước tính token, trước mọi lần gọi upstream, nên được báo là count_token_failed chứ không phải lỗi upstream.

Khi yêu cầu thất bại, khoản tạm giữ được hoàn lại.

Chuyển văn bản thành giọng nói — tạo âm thanh từ văn bản.
Models — xác nhận ID mô hình hiển thị với Key của bạn trước khi gọi endpoint âm thanh.
Giá mô hình — cách giá đầu vào và đầu ra âm thanh được hiển thị.
Lỗi thường gặp — mã trạng thái, body lỗi và thứ tự xử lý sự cố.