OpenRouter ra mắt API chuyển đổi giọng nói thành văn bản, hỗ trợ Whisper và tính phí theo token

Bạn có một bản ghi âm cuộc gọi bán hàng dài 40 phút, một thư mục chứa các bản ghi nhớ giọng nói, hoặc một người dùng đang giữ nút micrô và bạn cần chuyển đổi chúng thành văn bản. Cách thông thường là thiết lập một máy chủ Whisper hoặc thêm một SDK của nhà cung cấp thứ hai chỉ để chuyển đổi giọng nói thành văn bản (speech-to-text), bên cạnh hệ thống đã xử lý lưu lượng chat của bạn. Trên OpenRouter, bạn có thể gửi âm thanh đến POST /api/v1/audio/transcriptions thay thế và nhận lại JSON chứa văn bản đã được chuyển đổi cùng một đối tượng usage, sử dụng cùng khóa API và xác thực như Chat Completions.

Bạn không cần SDK mới hay một dịch vụ riêng biệt. Vì việc chuyển đổi văn bản chạy trên cùng nền tảng với lưu lượng chat của bạn, một mô hình được lưu trữ bởi nhiều nhà cung cấp sẽ được tự động cân bằng tải giữa các nhà cung cấp đó thay vì bị cố định vào một nhà cung cấp duy nhất.

Tóm tắt

Làm thế nào để chuyển đổi âm thanh thành văn bản trên OpenRouter?

Gửi âm thanh đã mã hóa base64 tới POST /api/v1/audio/transcriptions và đọc trường text từ phản hồi JSON. Bạn truyền khóa API OpenRouter của mình dưới dạng Bearer token giống hệt như khi thực hiện cuộc gọi chat, thiết lập mô hình và gửi âm thanh cho nó.

Phản hồi là một JSON chứa chuỗi văn bản lưu giữ bản ghi và một đối tượng usage báo cáo thời lượng âm thanh tính bằng giây, số lượng token và chi phí bằng đô la của yêu cầu. Bạn chỉ cần thực hiện một yêu cầu và bản ghi sẽ trả về trong phần thân phản hồi, vì vậy không cần phải thăm dò (polling) hay theo dõi job ID.

Phần thân yêu cầu chứa một mô hình và một đối tượng input_audio. Bên trong input_audio, bạn đặt tệp dưới dạng dữ liệu base64 và một chuỗi định dạng (format string). Tùy chọn, bạn có thể thêm gợi ý ngôn ngữ, nhiệt độ (temperature) và khối nhà cung cấp (provider block). Dưới đây là quy trình toàn diện:

Những mô hình speech-to-text nào hiện có sẵn?

Bạn có thể chọn từ hai nhóm mô hình. Các mô hình thuộc dòng Whisper như openai/whisper-1 được tính phí theo thời lượng, trên mỗi giây âm thanh, trong khi các mô hình speech-to-text mới hơn được tính phí theo token. Mô hình nào phù hợp phụ thuộc vào tiêu chuẩn độ chính xác, sự kết hợp ngôn ngữ và ngân sách của bạn.

ID của các mô hình STT không xuất hiện trong danh mục /api/v1/models mặc định. Điều này là bình thường, vì chuyển đổi văn bản là một phương thức đầu ra mà bạn cần lọc để tìm kiếm.

Lệnh đó sẽ trả về các mô hình speech-to-text cùng với mức giá hiện tại của từng mô hình. Danh sách tương tự cũng nằm trong bộ sưu tập Speech-to-Text nếu bạn muốn đọc dưới dạng một trang, và danh mục mô hình sẽ hiển thị mức giá trực tiếp cho từng mô hình.

Nếu bạn muốn thử một mô hình trước khi tích hợp, OpenRouter Playground cho phép chuyển đổi tệp đã tải lên ngay trên trình duyệt.

Hợp đồng yêu cầu theo từng trường

Toàn bộ quy trình gồm ba bước. Bạn mã hóa tệp sang base64, gửi POST với mô hình và định dạng, sau đó đọc text và usage từ phản hồi. Trường data nhận các byte base64 thô, không phải data: URI, vì vậy đừng thêm tiền tố data:audio/mp3;base64, vào trước. Trường format là bắt buộc, nó cho mô hình thượng nguồn biết cách giải mã các byte đó.

Endpoint này cũng chấp nhận các tệp tải lên theo kiểu multipart/form-data của OpenAI (tệp cộng với mô hình), giới hạn ở mức 25 MB. Nếu bạn đã có một client được xây dựng cho /v1/audio/transcriptions của OpenAI, bạn có thể trỏ URL cơ sở của nó đến https://openrouter.ai/api/v1 và nó sẽ hoạt động mà không cần thay đổi gì. Các tệp lớn hơn 25 MB sẽ đi qua đường dẫn JSON base64.

Gợi ý ngôn ngữ là tùy chọn. Nếu bạn bỏ qua, mô hình sẽ tự động phát hiện ngôn ngữ; việc thiết lập gợi ý sẽ loại bỏ một số mơ hồ trên các đoạn clip ngắn hoặc có nhiều tạp âm. Một số nhà cung cấp chấp nhận các tùy chọn bổ sung thông qua khối provider. Ví dụ, Groq chấp nhận một prompt cho từ vựng dự kiến thông qua provider.options.groq.prompt, giúp ích cho các danh từ riêng và thuật ngữ chuyên ngành mà mô hình có thể viết sai nếu không có gợi ý.

Phản hồi và việc hạch toán sử dụng

Phản hồi là JSON chứa chuỗi văn bản và đối tượng usage. Đối tượng usage là thứ cho phép bạn đo lường chi phí theo từng yêu cầu thay vì phải ước tính.

Giá trị chi phí đó là một ví dụ từ tài liệu của chúng tôi, không phải báo giá cố định; chi phí thực tế của bạn phụ thuộc vào mô hình và độ dài âm thanh. Đối tượng usage báo cáo số giây (thời lượng âm thanh), số lượng token và chi phí bằng đô la. Phản hồi cũng chứa header X-Generation-Id mà bạn có thể ghi lại để theo dõi hoặc gỡ lỗi một yêu cầu cụ thể sau này.

Khi nào nên sử dụng chuyển đổi văn bản (transcription) so với đầu vào âm thanh (audio input) hoặc chuyển đổi văn bản thành giọng nói (text-to-speech)?

Sử dụng /audio/transcriptions khi bạn muốn chuyển âm thanh thành văn bản, và sử dụng đầu vào âm thanh trong chat khi bạn muốn mô hình suy luận về âm thanh đó.

Endpoint chuyển đổi văn bản phù hợp cho ghi chú cuộc họp, lệnh thoại, tạo phụ đề và lưu trữ các cuộc gọi hoặc podcast có thể tìm kiếm được. Nếu bạn muốn phân tích cảm xúc trong một cuộc gọi hỗ trợ, hỏi đáp về nội dung đã nói, hoặc âm thanh kết hợp với các phương thức khác trong một prompt, hãy sử dụng loại nội dung input_audio trên /chat/completions. Việc chuyển đổi văn bản thành giọng nói là một endpoint thứ ba, riêng biệt.

Đối với cả phân tích âm thanh và chuyển đổi văn bản thành giọng nói, hãy xem thông báo về các API âm thanh.

Định tuyến nhà cung cấp cho chuyển đổi văn bản hoạt động như thế nào?

Chuyển đổi văn bản sử dụng cùng lớp định tuyến với chat. Khi một mô hình được lưu trữ bởi nhiều nhà cung cấp, chúng tôi phân phối các yêu cầu của bạn giữa họ, cân bằng tải theo giá, vì vậy bạn không bị cố định vào một nhà cung cấp duy nhất. Điều mà chuyển đổi văn bản hiện chưa hỗ trợ là kiểm soát định tuyến theo từng yêu cầu. Các trường order, only, allow_fallbacks, data_collection và sort mà bạn thiết lập trong cuộc gọi chat sẽ không được áp dụng trên /api/v1/audio/transcriptions. Khối provider trên endpoint này thay vào đó chứa các tùy chọn dành riêng cho nhà cung cấp:

Yêu cầu đó truyền cho Groq một gợi ý từ vựng cho các danh từ riêng mà nếu không có nó, mô hình có thể viết sai. Các tùy chọn được gắn khóa theo slug của nhà cung cấp và chỉ các tùy chọn của nhà cung cấp khớp mới được chuyển tiếp. Nếu bạn cần cố định một nhà cung cấp cụ thể hoặc thực thi chính sách dữ liệu theo từng yêu cầu trên một bản chuyển đổi, quyền kiểm soát đó hiện chưa khả dụng trên endpoint này. Đối tượng provider đầy đủ được ghi lại trong tài liệu định tuyến nhà cung cấp.

OpenRouter không tính thêm phí so với giá của nhà cung cấp, vì vậy mức giá trong danh mục là mức giá bạn phải trả, và chính sách Zero Completion Insurance nghĩa là một bản chuyển đổi thất bại sẽ không bị tính phí. Nếu bạn đã có thỏa thuận với nhà cung cấp, BYOK cho phép bạn định tuyến thông qua khóa nhà cung cấp của riêng mình và chỉ trả phí nền tảng của chúng tôi thay vì chi phí mô hình theo mức sử dụng, với phí được miễn cho 1 triệu yêu cầu đầu tiên mỗi tháng theo hình thức trả tiền theo mức sử dụng (pay-as-you-go).

Những giới hạn nào cần lưu ý khi lập kế hoạch?

Bốn ràng buộc định hình cách bạn cấu trúc một cuộc gọi chuyển đổi văn bản:

Vì thời gian chờ (timeout) giới hạn thời gian xử lý thay vì độ dài âm thanh, thời lượng của một clip không cho bạn biết liệu nó có phù hợp hay không. Một bản ghi kéo dài hàng giờ, như một phiên chơi game qua đêm, cần được xử lý theo kiểu chia nhỏ (chunking); một cuộc gọi đơn lẻ sẽ không thể xử lý hết.

Đối với phụ đề, phản hồi mặc định là văn bản cộng với mức sử dụng mà không có thời gian. Hãy đặt response_format thành verbose_json và bạn sẽ nhận được dấu thời gian ở cấp độ phân đoạn, cộng với cấp độ từ nếu bạn truyền timestamp_granularities: ["word"]. Điều này hoạt động trên các nhà cung cấp tương thích với OpenAI (OpenAI, Groq, Together); các nhà cung cấp khác sẽ từ chối với mã lỗi 400. Không có đầu ra.srt/.vtt tích hợp sẵn, vì vậy bạn phải tự xây dựng tệp phụ đề từ các dấu thời gian.

Một yêu cầu chuyển đổi văn bản tốn bao nhiêu chi phí?

Bạn trả theo mức giá trong danh mục của mô hình mà không có phí cộng thêm từ chúng tôi, và trường usage.cost cho bạn biết con số chính xác cho mỗi yêu cầu. Các mô hình dòng Whisper tính phí theo giây âm thanh, và các mô hình mới hơn tính phí theo token.

Giá cả thay đổi, vì vậy chúng tôi giữ con số trực tiếp trên trang của mỗi mô hình trong danh mục thay vì in ra ở đây. Đọc usage.cost từ phản hồi sẽ cho bạn biết chi phí thực tế của mỗi yêu cầu. Các mô hình STT là dịch vụ trả phí, vì vậy việc chuyển đổi văn bản qua API sẽ trừ vào số dư tín dụng của bạn.

Để bắt đầu, hãy xác nhận mô hình phù hợp với âm thanh của bạn trong Playground, thiết lập cuộc gọi và đọc usage.cost cho mỗi yêu cầu để đo lường chi tiêu ngay từ ngày đầu tiên.

Các câu hỏi thường gặp

Làm thế nào để tôi chuyển đổi các tệp âm thanh bằng OpenRouter?

Gửi âm thanh đã mã hóa base64 tới POST /api/v1/audio/transcriptions với một mô hình và một đối tượng input_audio (dữ liệu cộng với định dạng). Phản hồi là JSON với chuỗi văn bản (bản ghi) và đối tượng usage (giây, token và chi phí). Nó sử dụng cùng khóa API Bearer và xác thực như Chat Completions.

OpenRouter có hỗ trợ Whisper không?