Whisper-1 API：完成首次音频转录

首次调用 Whisper-1 API 需要一个音频文件、明确的模型 ID 和输出格式。在 SeedRouter 上传录音后，保存返回的任务 ID，等任务完成再下载转录稿。先用一段内容已知的短录音：这样更容易发现漏词和异常拼写。

本指南采用 SeedRouter 的异步契约，不能直接当作 OpenAI SDK 的同步示例使用。Whisper-1 模型页 提供 Playground 与实时价格；API 参考文档 列出全部字段和尚未完成的兼容性检查。^[1]

准备一段录音

请使用你有权处理的语音。简短的 WAV 或 MP3 适合首次尝试。当前上传上限为 26,214,400 字节；文件必须包含可读取且时长可测量的音频。给文本文件改成 .mp3 扩展名并不会使其成为有效音频。参考文档区分了文档记载的九种输入格式与已通过真实检查的格式。^[1]

以下录音是专为本教程制作的原创英文合成语音。封面展示了它的波形。封面引用的句子来自录音脚本，并非准确率声明。

下载 10.31 秒示例。脚本原文为：“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.”

把 API 密钥保存在服务端环境变量中。不要将其放入公开网页、移动应用包或共享截图。以下 Python 示例使用 requests，从环境变量读取 SEEDROUTER_API_KEY。

只提交一次 Whisper-1 API 请求

首次请求选择 json。这样就能读取下载结果的 text 字段，无需处理字幕时间码。multipart 的 file 部分必须包含真实字节；将 URL 作为其值不等于上传文件。让客户端设置 multipart 内容类型和 boundary。^[1]

保存为 transcribe.py。脚本在 POST 前写入提交标记，并在请求被接收后保存任务 ID。再次运行时会读取已有任务。若 POST 结果不确定，标记会阻止脚本意外创建重复请求。

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"])

运行 python transcribe.py。若输出 processing，等待几秒后再次运行同一命令。脚本会读取已保存的 ID，而非重新上传。每次有意处理新录音时，请使用独立状态文件。仅凭客户端超时不能判断任务失败。

读取完成的转录稿

接收响应包含 id、model、status 和 created_at。完成后会增加 output.url 与 output.format。该 URL 指向结果文件；它不是需要再次付费请求的媒体生成任务。通过 GET 即可下载结果。^[1]

边听录音边阅读文字。将文本用于字幕或精确引用之前，核对姓名、数字和句子边界。转录稿是口述内容的初稿，时间戳也不能免除人工核对。

2026 年 10 月 19 日的本地端到端检查完成了全部五种转录格式和一次英文输入翻译。这些检查验证了受测录音的交付与计费行为，并不能证明准确率百分比或跨语言翻译质量。

选择文本、时间戳或字幕

需要词级时间戳时，发送 response_format=verbose_json，并添加名为 timestamp_granularities[]、值为 word 的可重复 multipart 字段。若同时需要片段时间戳，再添加一个值为 segment 的部分。Python requests 使用 (name, value) 对组成的列表表示重复字段。各时间戳单位为秒。^[2]

词级时间戳和说话人标签是不同的输出。仅仅请求片段，并不会让 Whisper-1 将会议转成带说话人标签的稿件。该模型也不流式返回部分文本：stream 会被忽略。使用已验证路径时，请省略 chunking_strategy；显式选择 auto 未通过真实兼容性检查。^[1]

按需添加语言和拼写上下文

可选的 language=en 告诉转录请求输入为英文。希望自动检测时请省略。产品名称容易误听时，可在 prompt 中用与音频相同的语言提供正确拼写。Whisper 提示词提供上下文，不像聊天指令那样能可靠地要求特定排版。^[3]

上下文应与片段相关。Whisper 只使用其分词器的最后 224 个 token。发送长文档不会让录音拥有无限术语表，字符计数也不能可靠地替代该 token 规则。

翻译成英文时，将端点改为 /audio/translations。其五个请求字段是 file、model、prompt、response_format 和 temperature。翻译输出英文，没有目标语言选择器。若提供提示词，请使用英文。^[4]

扩展工作流前先检查费用

下方实时表格使用实测音频时长。同一录音的转录稿变长，不会增加时长费用。每个文件的时长先向上取整到整秒，再换算成音频计量单位。API 参考文档提供精确公式，Playground 在能读取录音时长后显示预估费用。失败的请求不收费。

处理大量文件之前，先验证一段具有代表性的录音并检查结果。保留每段录音的任务 ID，这样连接中断后可以通过查询已有状态恢复。添加字幕或测试较少的格式组合之前，请阅读完整参数参考。

首次接入常见问题

能直接使用 OpenAI Python SDK 示例吗？

不能。multipart 输入字段虽然熟悉，但 SeedRouter 返回异步任务 ID。期待 POST 响应直接包含 text 的同步客户端需要适配。本文示例明确区分提交与读取结果。

为什么 JSON 结果没有词级时间戳？

默认 json 格式主要用于文本。请同时请求 verbose_json 和 word 时间戳粒度。仅有片段时间信息不会为每个词创建条目。

超时后应该再发一次 POST 吗？

先检查已保存的任务 ID 或任务历史。请求可能已被接收，只是响应丢失。读取已有任务可避免为同一录音创建另一个请求。

Whisper-1 要停用了吗？

OpenAI 已宣布其自有 API 上的 Whisper 将于 2027 年 2 月 26 日关闭。此公告不代表本服务的关闭日期。构建新集成时，应将生命周期公告纳入维护检查。^[5]

来源

[1] SeedRouter Whisper-1 API 参考文档与验证状态，检查日期：2026 年 10 月 19 日。

[2] OpenAI 转录参考文档。

[3] OpenAI Whisper 提示词指南。

[4] OpenAI 翻译参考文档。

[5] OpenAI 转录模型弃用公告。