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

Thông tin chung

• Base URL: https://api.routeapi.ai
• Xác thực: Authorization: Bearer $ROUTEAPI_KEY với API Key bắt đầu bằng sk- (tạo trên trang API Keys trong console). Management Key bắt đầu bằng rat_ không thể gọi mô hình.
• Định dạng lỗi: {"error": {"message": "...", "type": "...", "code": "..."}}. Xem Lỗi thường gặp để biết ý nghĩa từng mã trạng thái.

Chuyển văn bản thành giọng nói đọc một đoạn văn bản và trả về tệp âm thanh. Endpoint theo đúng quy ước của OpenAI: request body là JSON, response body chính là âm thanh, không có tác vụ bất đồng bộ hay bước thăm dò.

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

Danh sách mô hình không đánh dấu mô hình âm thanh

Các loại endpoint tích hợp sẵn của RouteAPI không có giá trị audio, nên không thể phân biệt mô hình TTS với mô hình chat trong GET /v1/models: supported_endpoint_types của nó phản ánh loại kênh đang phục vụ nó (thường là openai). Hãy chọn ID mô hình từ danh sách rồi gọi đường dẫn âm thanh với ID đó. Xem Models.

Endpoint

POST /v1/audio/speech

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

Tham số yêu cầu

Body là JSON. Chỉ model được chính RouteAPI kiểm tra; các trường còn lại được chuyển tiếp tới mô hình upstream, và các giá trị được chấp nhận phụ thuộc vào mô hình đó.

Trường	Kiểu	Bắt buộc	Mô tả
model	string	Có	ID mô hình TTS, ví dụ tts-1, tts-1-hd hoặc gpt-4o-mini-tts. Trường này bắt buộc phải có trong body: giá trị rỗng hoặc thiếu sẽ trả về 400 với Missing required field: model (định tuyến có dự phòng tts-1, nhưng bước kiểm tra chạy trước)
input	string	Upstream bắt buộc	Văn bản cần tổng hợp thành giọng nói. Gateway cũng ước tính token đầu vào từ trường này để tính phí
voice	string	Upstream bắt buộc	Tên giọng nói. Tập giọng hợp lệ phụ thuộc vào từng mô hình
response_format	string	Không	Định dạng chứa âm thanh, được chuyển tiếp tới upstream. Khi bỏ qua, giá trị mặc định của upstream được áp dụng. Gateway cũng dùng giá trị này để đo thời lượng âm thanh trả về nhằm tính phí và coi giá trị bị bỏ qua là mp3; pcm được đo ở 24 kHz, 16-bit, mono
speed	number	Không	Hệ số tốc độ phát, được chuyển tiếp nguyên vẹn khi có
instructions	string	Không	Chỉ dẫn về cách thể hiện/phong cách cho các mô hình hỗ trợ (như gpt-4o-mini-tts)
stream_format	string	Không	Đặt thành sse để nhận âm thanh dưới dạng Server-Sent Events thay vì một body nhị phân. Giá trị được chuyển tiếp; chỉ những upstream hỗ trợ TTS streaming mới thực sự stream
metadata	object	Không	Các trường bổ sung mà một số loại kênh hợp nhất vào yêu cầu upstream của riêng chúng (ví dụ Volcengine TTS hoặc MiniMax)

Ví dụ

curl

curl https://api.routeapi.ai/v1/audio/speech \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-1",
    "voice": "alloy",
    "input": "RouteAPI aggregates many AI providers behind a single API.",
    "response_format": "mp3"
  }' \
  --output speech.mp3

Python (SDK OpenAI)

import os

from openai import OpenAI

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

with client.audio.speech.with_streaming_response.create(
    model="tts-1",
    voice="alloy",
    input="RouteAPI aggregates many AI providers behind a single API.",
    response_format="mp3",
) as response:
    response.stream_to_file("speech.mp3")

client.audio.speech.create(...) cũng dùng được và trả về response.content, dữ liệu âm thanh thô. Lưu lại bằng open("speech.mp3", "wb").write(response.content).

Phản hồi

Body chính là tệp âm thanh, không phải JSON. Gateway đọc body upstream để đo thời lượng nhằm tính phí, sau đó ghi ra kèm Content-Length khớp với những gì bạn thực sự nhận được. Chỉ một danh sách trắng nhỏ các header upstream được chuyển tiếp — đáng chú ý là Content-Type (ví dụ audio/mpeg), bạn có thể dựa vào đó để chọn phần mở rộng tệp; các header upstream khác như Server bị loại bỏ. Content-Encoding chỉ được chuyển tiếp khi body upstream chưa được gateway giải nén.

Với "stream_format": "sse", phản hồi là text/event-stream. Mỗi đoạn âm thanh đến dưới dạng một frame data:, và nếu upstream gửi một chunk usage cuối cùng thì gateway đọc nó để tính phí; nếu không, gateway tính phí theo ước tính.

Tính phí

Các lần gọi âm thanh 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.

Phương thức áp dụng phụ thuộc vào cách mô hình được định giá, và trang chi tiết mô hình sẽ hiển thị điều đó:

• Giá cố định theo lần yêu cầu. Nếu mô hình có cấu hình giá theo lần yêu cầu, yêu cầu được tính đúng giá đó nhân với hệ số nhóm của bạn và token không ảnh hưởng tới số tiền. Trong bộ mặc định tích hợp sẵn, gpt-4o-mini-tts đã được cấu hình theo cách này — hãy kiểm tra trang chi tiết thay vì giả định là tính phí theo token.
• Theo token. Nếu không, khoản phí được tính từ mức sử dụng bên dưới.

Đầu vào

Đầu vào được ước tính từ input. Gateway đếm ký tự với hầu hết mô hình và dùng tokenizer với các mô hình có ID chứa gpt, sau đó tính phí số đó theo hệ số của mô hình.

Đầu ra

Âm thanh được tạo được đo bằng token theo 1000 token mỗi phút âm thanh: gateway đọc thời lượng từ âm thanh trả về và tính ceil(duration) / 60 × 1000 token đầu ra, với giá bằng hệ số của mô hình nhân hệ số âm thanh nhân hệ số hoàn thành âm thanh. Nếu không đo được thời lượng âm thanh, gateway dự phòng khoảng một token cho mỗi kilobyte âm thanh.

Hệ số hoàn thành âm thanh tích hợp sẵn là 0 với dòng tts-1 / tts-1-hd, nên khi tính phí theo token, âm thanh được tạo không cộng thêm gì cho các mô hình đó và phần đầu vào dựa trên ký tự thực chất là toàn bộ khoản phí. Các mô hình có hệ số hoàn thành âm thanh khác 0 còn bị tính phí cho âm thanh được tạo.

Việc đo thời lượng phụ thuộc vào response_format: pcm không có header định dạng chứa, nên thời lượng được tính từ số byte ở 24 kHz / 16-bit / mono; các định dạng khác được phân tích từ định dạng chứa.

Vì token đầu ra được suy ra từ tệp trả về, khoản phí phản ánh những gì thực sự được tạo, không chỉ độ dài của input.

Lỗi

Lỗi 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	convert_request_failed	Không thể chuyển đổi yêu cầu cho kênh — ví dụ kênh có bộ chuyển đổi chưa triển khai chuyển văn bản thành giọng nói
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"
  }
}

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

Tiếp theo

• Chuyển giọng nói thành văn bản — phiên âm hoặc dịch tệp âm thanh.
• Models — xác nhận ID mô hình hiển thị với Key của bạn trước khi gọi.
• 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ố.