Whisper-1 API: Phiên âm đầu tiên của bạn bằng Python

Yêu cầu Whisper-1 API đầu tiên cần một tệp âm thanh, ID mô hình được chỉ định rõ và định dạng đầu ra. Trên SeedRouter, bạn tải bản ghi, lưu ID tác vụ được trả về rồi tải bản phiên âm khi tác vụ hoàn tất. Bắt đầu với bản ghi ngắn mà bạn đã biết nội dung để dễ nhận ra từ bị thiếu hoặc cách viết bất thường.

Hướng dẫn này theo hợp đồng bất đồng bộ của SeedRouter. Đây không phải ví dụ OpenAI SDK đồng bộ có thể dùng thay thế nguyên trạng. Trang mô hình Whisper-1 có Playground và giá trực tiếp; tài liệu tham khảo API liệt kê mọi trường và các kiểm tra tương thích còn chưa hoàn thành. ^[1]

Chuẩn bị một bản ghi

Dùng giọng nói mà bạn có quyền xử lý. WAV hoặc MP3 ngắn là điểm khởi đầu hữu ích. Giới hạn tải lên hiện tại là 26,214,400 byte; tệp phải chứa âm thanh đọc được với thời lượng đo được. Đổi phần mở rộng tệp văn bản thành .mp3 không làm nó trở thành âm thanh hợp lệ. Tài liệu tham khảo phân biệt chín định dạng đầu vào được ghi trong tài liệu với các định dạng đã qua kiểm tra thực tế. ^[1]

Bản ghi dưới đây là giọng nói tiếng Anh tổng hợp gốc, được tạo riêng cho hướng dẫn này. Dạng sóng của nó xuất hiện trên ảnh bìa. Câu trích trên bìa lấy từ kịch bản ghi âm, không phải tuyên bố về độ chính xác.

Tải mẫu 10,31 giây. Kịch bản nguyên văn: “This is a sample recording for an audio transcription tutorial. Our meeting starts at nine thirty on Monday. Please bring the project notes and review the final checklist before we begin.”

Giữ khóa API trong biến môi trường phía máy chủ. Không đặt nó trong trang web công khai, gói ứng dụng di động hay ảnh chụp màn hình chia sẻ. Ví dụ Python dưới đây dùng requests và đọc SEEDROUTER_API_KEY từ môi trường.

Chỉ gửi yêu cầu Whisper-1 API một lần

Chọn json cho yêu cầu đầu tiên. Bạn có thể đọc trường text của tệp kết quả tải xuống mà không xử lý mã thời gian phụ đề. Phần file trong multipart phải chứa byte thực; cung cấp URL làm giá trị không tương đương tải tệp lên. Để client đặt kiểu nội dung multipart và boundary. ^[1]

Lưu đoạn này thành transcribe.py. Nó ghi dấu gửi trước POST và lưu ID tác vụ sau khi được chấp nhận. Chạy lại sẽ đọc tác vụ hiện có. Nếu kết quả POST không rõ, dấu này ngăn mã vô tình tạo bản gửi trùng.

import json
import os
from pathlib import Path

import requests

base = "https://api.seedrouter.ai/v1"
headers = {"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"}
state = Path("whisper-task.json")
audio = Path("recording.wav")

if not state.exists():
    if not 0 < audio.stat().st_size <= 26_214_400:
        raise ValueError("Choose a nonempty recording within the upload limit")
    with state.open("x") as marker:
        json.dump({"status": "submission_unconfirmed"}, marker)
    with audio.open("rb") as recording:
        response = requests.post(
            f"{base}/audio/transcriptions",
            headers=headers,
            files={"file": (audio.name, recording, "audio/wav")},
            data={"model": "whisper-1", "response_format": "json"},
            timeout=180,
            allow_redirects=False,
        )
    response.raise_for_status()
    accepted = response.json()
    task_id = accepted.get("id")
    if not isinstance(task_id, str) or not task_id.startswith("task_"):
        raise RuntimeError("Submission could not be confirmed; check task history")
    state.write_text(json.dumps({"id": task_id}), encoding="utf-8")

saved = json.loads(state.read_text(encoding="utf-8"))
if "id" not in saved:
    raise RuntimeError("Check task history before submitting another recording")

response = requests.get(
    f"{base}/tasks/{saved['id']}", headers=headers, timeout=30,
    allow_redirects=False,
)
response.raise_for_status()
task = response.json()
print(task["status"])
if task["status"] == "completed":
    result = requests.get(task["output"]["url"], timeout=60)
    result.raise_for_status()
    print(result.json()["text"])
elif task["status"] == "failed":
    print(task["error"])

Chạy python transcribe.py. Nếu in ra processing, chờ vài giây rồi chạy lại cùng lệnh. Mã sẽ đọc ID đã lưu thay vì tải lên lần nữa. Lưu tệp trạng thái riêng cho từng bản ghi mới mà bạn chủ ý xử lý. Chỉ riêng việc client hết thời gian chờ không chứng minh tác vụ thất bại.

Đọc bản phiên âm hoàn tất

Phản hồi chấp nhận có id, model, status và created_at. Khi hoàn tất, output.url và output.format được thêm vào. URL đó trỏ đến tệp kết quả, không phải tác vụ tạo nội dung cần thêm yêu cầu trả phí. GET sẽ tải tệp kết quả. ^[1]

Đọc văn bản trong lúc nghe bản ghi. Kiểm tra tên, số liệu và ranh giới câu trước khi dùng làm phụ đề hoặc trích dẫn nguyên văn. Bản phiên âm là bản nháp của lời nói; dấu thời gian không loại bỏ nhu cầu kiểm tra.

Các kiểm tra đầu cuối cục bộ ngày 19 tháng 10 năm 2026 đã hoàn thành cả năm định dạng phiên âm và một bản dịch với đầu vào tiếng Anh. Chúng xác nhận hành vi cung cấp kết quả và tính phí cho các bản ghi được thử. Chúng không xác định tỷ lệ chính xác hay chất lượng dịch giữa các ngôn ngữ.

Chọn văn bản, dấu thời gian hoặc phụ đề

Bước tiếp theo	Chọn	Đọc tệp tải xuống dưới dạng
Đưa nội dung vào ứng dụng	`json`	JSON; bắt đầu với `text`
Sửa bản phiên âm thuần văn bản	`text`	Văn bản thuần
Nhập phụ đề vào trình biên tập	`srt` hoặc `vtt`	Văn bản phụ đề
Căn chỉnh từng từ hoặc đoạn	`verbose_json`	JSON có dấu thời gian được yêu cầu

Để có dấu thời gian từng từ, gửi response_format=verbose_json và trường multipart lặp tên timestamp_granularities[] với giá trị word. Thêm một phần khác có giá trị segment nếu cần cả hai. Trong Python requests, dùng danh sách cặp (name, value) cho trường lặp. Mỗi dấu thời gian tính bằng giây. ^[2]

Dấu thời gian từng từ và nhãn người nói là các đầu ra khác nhau. Whisper-1 không biến cuộc họp thành bản phiên âm có nhãn người nói chỉ vì bạn yêu cầu các đoạn. Nó cũng không truyền dần văn bản từng phần: stream bị bỏ qua với mô hình này. Bỏ qua chunking_strategy để dùng luồng đã kiểm chứng; chọn rõ auto đã không vượt qua kiểm tra tương thích thực tế. ^[1]

Thêm ngôn ngữ và ngữ cảnh cách viết khi cần

language=en tùy chọn cho yêu cầu phiên âm biết đầu vào là tiếng Anh. Bỏ qua nếu muốn tự phát hiện. Nếu tên sản phẩm dễ bị nghe sai, đưa cách viết đúng vào prompt, dùng cùng ngôn ngữ với âm thanh. Prompt Whisper cung cấp ngữ cảnh; nó không hoạt động như lệnh trò chuyện có thể yêu cầu một bố cục nhất định một cách đáng tin cậy. ^[3]

Giữ ngữ cảnh liên quan đến đoạn âm thanh. Whisper chỉ dùng 224 token cuối theo bộ tách token riêng. Gửi tài liệu dài không tạo cho bản ghi một bảng thuật ngữ vô hạn, và đếm ký tự không thay thế đáng tin cậy cho quy tắc token này.

Để dịch sang tiếng Anh, đổi điểm cuối thành /audio/translations. Năm trường yêu cầu là file, model, prompt, response_format và temperature. Dịch tạo tiếng Anh; không có lựa chọn ngôn ngữ đích. Dùng prompt tiếng Anh nếu bạn cung cấp. ^[4]

Kiểm tra phí trước khi mở rộng quy trình

Bảng giá trực tiếp dưới đây dùng thời lượng âm thanh đo được. Với cùng một bản ghi, bản phiên âm dài hơn không làm tăng phí thời lượng. Thời lượng từng tệp được làm tròn lên giây nguyên rồi đổi thành đơn vị đo âm thanh. Tài liệu tham khảo API có phép tính chính xác, và Playground hiển thị ước tính khi đọc được thời lượng bản ghi. Yêu cầu thất bại không bị tính phí.

Model	USD per minute	USD per million audio metering units
whisper-1	$0.036	$36

For each recording: units = round(ceil(duration in seconds) × 1000 / 60). Multiply these audio units by the live unit rate. These are duration units, not transcript tokens. Both transcription and English translation use this rule. Failed requests are not charged.

Trước khi xử lý nhiều tệp, xác thực một bản ghi đại diện và xem kết quả. Giữ ID tác vụ của từng bản ghi để có thể khôi phục sau gián đoạn kết nối bằng cách đọc trạng thái hiện có. Xem toàn bộ tham số trước khi thêm phụ đề hoặc các tổ hợp định dạng ít được kiểm thử hơn.

[3] Hướng dẫn prompt Whisper của OpenAI.

[4] Tài liệu tham khảo dịch OpenAI.

[5] Thông báo ngừng hỗ trợ mô hình phiên âm OpenAI.

Whisper-1 API: Bản phiên âm đầu tiên của bạn

Chuẩn bị một bản ghi

Chỉ gửi yêu cầu Whisper-1 API một lần

Đọc bản phiên âm hoàn tất

Chọn văn bản, dấu thời gian hoặc phụ đề

Thêm ngôn ngữ và ngữ cảnh cách viết khi cần

Kiểm tra phí trước khi mở rộng quy trình

Câu hỏi khi tích hợp lần đầu

Tôi có thể dùng nguyên ví dụ OpenAI Python SDK không?

Vì sao kết quả JSON không có dấu thời gian từng từ?

Tôi có nên gửi POST khác sau khi hết thời gian chờ?

Whisper-1 sắp ngừng hoạt động sao?

Nguồn

Hướng dẫn liên quan

Dùng Kling 4.0 API: chế độ, khung hình chính, tham chiếu, chỉnh sửa

DeepSeek Search API: giá và ví dụ tìm kiếm rồi dùng Fetch bằng Python

Gemini 4 Argon API: trò chuyện Python với luồng theo định dạng gốc