Hướng dẫn 5 phút sử dụng API chuyển văn bản thành giọng nói trên OpenRouter

Chúng tôi hỗ trợ chuyển đổi văn bản thành giọng nói (text-to-speech) thông qua endpoint POST /api/v1/audio/speech tương thích với OpenAI. Bạn chỉ cần gửi văn bản, chọn model và giọng đọc được hỗ trợ, sau đó lưu hoặc phát trực tuyến âm thanh. Một API key duy nhất có thể truy cập các model TTS từ nhiều nhà cung cấp khác nhau bằng cùng một cấu trúc yêu cầu.

Hướng dẫn này bao gồm các nội dung về xác thực, tổng hợp giọng nói, xác thực phản hồi, phát trực tuyến (streaming) và cách thay đổi model hoặc giọng đọc.

Tóm tắt (Tl;dr)

Bạn chỉ định tên model trong phần thân yêu cầu (request body). Endpoint, xác thực và cách xử lý phản hồi vẫn giữ nguyên bất kể bạn chọn model giọng nói của nhà cung cấp nào.

Thông báo về API âm thanh của chúng tôi bao gồm thông tin về đợt ra mắt rộng rãi hơn. Đối với chuyển đổi giọng nói thành văn bản (speech-to-text), hãy sử dụng hướng dẫn phiên âm của chúng tôi.

Những gì bạn cần để sử dụng tính năng text-to-speech của OpenRouter

Tạo một OpenRouter API key và lưu nó vào biến môi trường để tránh lộ trong mã nguồn của bạn.

Trên macOS hoặc Linux, hãy thiết lập biến này cho phiên terminal hiện tại của bạn:

Tất cả các ví dụ đều sử dụng https://openrouter.ai/api/v1 làm URL cơ sở và gửi key trong header Authorization: Bearer.

Endpoint chấp nhận hai trường bắt buộc cùng với một giọng đọc mà hầu hết các model đều yêu cầu:

response_format và speed là các tùy chọn không bắt buộc, nhưng việc thiết lập định dạng đầu ra một cách rõ ràng sẽ giúp phản hồi dễ dự đoán hơn vì khả năng hỗ trợ định dạng khác nhau tùy theo từng model. Endpoint của chúng tôi mặc định là PCM nếu bạn bỏ qua response_format, trong khi Mistral Voxtral Mini TTS chỉ chấp nhận MP3, và speed chỉ thay đổi tốc độ nói trên các model hỗ trợ tính năng này.

Một yêu cầu thành công sẽ trả về dữ liệu âm thanh thô (raw audio bytes), trong khi yêu cầu không thành công sẽ trả về JSON. Hãy xác thực phản hồi trước khi ghi nó vào tệp âm thanh.

Khi đã nắm rõ về key và cách xử lý phản hồi, bạn có thể tạo tệp âm thanh đầu tiên của mình.

Tạo tệp MP3 đầu tiên bằng cURL

Yêu cầu sau đây sử dụng Mistral Voxtral Mini TTS và giọng đọc en_paul_neutral của nó. Nó lưu trực tiếp các byte trả về vào tệp output.mp3.

Các cờ (flags) này giúp bạn xử lý các yêu cầu thất bại một cách chính xác. --fail-with-body khiến cURL thoát ra kèm lỗi khi nhận phản hồi 4xx hoặc 5xx, và vì --output đã được thiết lập, nó sẽ ghi nội dung lỗi JSON của máy chủ vào output.mp3 thay vì hiển thị trên terminal. Khi lệnh thất bại, hãy đọc lỗi bằng cat output.mp3 và xóa tệp trước khi thử lại để tránh việc phát nhầm tệp JSON như một tệp âm thanh. --dump-header lưu lại các header phản hồi để bạn có thể xác nhận loại nội dung (content type) và nắm bắt ID tạo (generation ID).

Trước khi phát âm thanh, hãy xác nhận rằng output.mp3 đã tồn tại và chứa dữ liệu:

Trên macOS, bạn có thể phát tệp bằng lệnh afplay output.mp3. Trên Linux, hãy sử dụng trình phát đã cài đặt như ffplay.

Khi đưa yêu cầu này vào mã ứng dụng, hãy xác nhận rằng yêu cầu đã thành công và phản hồi có chứa âm thanh trước khi lưu lại. Các bước kiểm tra này giúp ngăn chặn việc ghi phản hồi lỗi JSON vào tệp MP3.

Tạo và lưu giọng nói bằng Python

Cài đặt thư viện requests nếu dự án của bạn chưa sử dụng nó:

Ví dụ này kiểm tra trạng thái HTTP và xác minh rằng chúng ta đã nhận được dữ liệu MP3 trước khi lưu tệp:

raise_for_status sẽ đưa ra ngoại lệ khi API trả về phản hồi 4xx hoặc 5xx, ngăn ứng dụng lưu nội dung lỗi dưới dạng âm thanh. Nếu yêu cầu thành công, việc kiểm tra content-type sẽ xác nhận rằng phản hồi có chứa âm thanh trước khi ghi vào tệp. Hãy ghi lại X-Generation-Id để bạn có thể truy vết yêu cầu hoặc cung cấp thông tin tham chiếu khi liên hệ với bộ phận hỗ trợ.

Quy trình xác thực tương tự cũng áp dụng khi một SDK quản lý luồng phản hồi. Ví dụ tiếp theo giữ nguyên URL cơ sở của OpenRouter và chuyển việc xử lý tệp sang client Python của OpenAI.

Phát trực tuyến phản hồi với OpenAI Python SDK

Endpoint TTS của chúng tôi tuân theo cấu trúc của OpenAI Audio Speech API. Bạn có thể trỏ client OpenAI vào URL cơ sở của chúng tôi và phát trực tuyến phản hồi HTTP vào một tệp:

Mô hình này đọc phản hồi theo từng phần trong khi lưu tệp. Việc phát lại lũy tiến (progressive playback) yêu cầu một trình phát có khả năng đệm (buffer) các đoạn dữ liệu đến.

JavaScript có thể đọc cùng một phản hồi thông qua arrayBuffer. Ví dụ này kiểm tra trạng thái và loại nội dung trước khi tạo tệp:

Hãy chọn MP3 khi bạn cần một tệp có dung lượng nhỏ hơn và tương thích với các trình phát âm thanh tiêu chuẩn. PCM tránh được chi phí nén và có thể giảm độ trễ trong các đường ống phát trực tuyến thời gian thực tương thích. Chúng tôi trả về MP3 dưới dạng audio/mpeg và PCM dưới dạng audio/pcm, tùy chọn kèm theo các tham số về tốc độ lấy mẫu (rate) và kênh (channels), mặc dù các định dạng khả dụng phụ thuộc vào model được chọn. Mistral Voxtral Mini TTS chỉ chấp nhận MP3, vì vậy yêu cầu PCM sẽ trả về lỗi 400. Việc phát PCM thô cũng yêu cầu các cài đặt âm thanh chính xác vì chỉ đổi phần mở rộng tệp thành.mp3 sẽ không chuyển đổi được định dạng âm thanh.

Mã vận chuyển (transport code) vẫn giữ nguyên trên các model được hỗ trợ. Các trường model và voice phải là một cặp hợp lệ.

Thay đổi model và giọng đọc TTS

Các định danh giọng đọc (voice identifiers) thuộc về các model cụ thể. Việc so sánh giọng đọc trong cùng một model có thể chỉ cần thay đổi một dòng. Ví dụ, trang model Grok Voice TTS 1.0 hiện tại liệt kê năm giọng đọc tích hợp: eve, ara, rex, sal và leo.

Bắt đầu với cặp model và giọng đọc này:

Sau đó chỉ thay đổi dòng giọng đọc:

Ví dụ về Grok cũng minh họa việc thay đổi nhà cung cấp từ Mistral sang xAI. Hãy cập nhật model và giọng đọc cùng nhau, vì mỗi nhà cung cấp hiển thị các ID model và giọng đọc riêng của họ, trong khi endpoint, xác thực, đầu vào và các bước kiểm tra phản hồi vẫn không thay đổi:

Hãy xác nhận cả hai giá trị trên trang model đã chọn trước khi gửi yêu cầu vì tính khả dụng của model và danh mục giọng đọc có thể thay đổi.

Sử dụng Models API để truy xuất các model TTS hiện tại:

Bạn cũng có thể duyệt qua bộ sưu tập model text-to-speech của chúng tôi.

Tài liệu TTS của chúng tôi mô tả các tùy chọn dành riêng cho nhà cung cấp mà bạn có thể truyền qua provider.options.<provider> đối với các model hỗ trợ chúng. Tính đến tháng 9 năm 2026, không có model giọng nói nào của OpenAI nằm trong danh mục trực tuyến, vì vậy hãy kiểm tra danh sách model hiện tại trước khi dựa vào một trường dành riêng cho nhà cung cấp.