如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

文件转写

将录音中的语音转换为文本。

如果录音已完成,或请求中的音频有明确的起止范围,请使用文件转写。上传音频后,您可以接收最终的转写文本,也可以在模型处理文件时以流式方式接收文本。

请先使用 gpt-transcribe。这是按录音原始语言转写语音的推荐模型。下文关于说话人标注、词级时间戳和字幕格式的示例使用的是已弃用的模型。

whisper-1、gpt-4o-transcribe、gpt-4o-mini-transcribe、gpt-4o-transcribe-diarize 和 /v1/audio/translations 均已弃用,将于 2027 年 2 月 26 日停止服务。请参阅弃用公告,并选择当前支持的转写工作流。下文的专项示例说明现有集成在服务停止前仍可使用哪些功能。

文件大小上限为 25 MB。支持的输入格式包括 flac、mp3、mp4、mpeg、mpga、m4a、ogg、wav 和 webm。

如果仍在从麦克风、通话或媒体流接收音频,请使用实时转写。

快速入门

转写

将音频文件发送到 /v1/audio/transcriptions,并指定 gpt-transcribe 模型:

转写音频
from openai import OpenAI

client = OpenAI()
audio_file = open("audio.wav", "rb")

transcription = client.audio.transcriptions.create(
    model="gpt-transcribe", file=audio_file
)

print(transcription.text)

模型以 JSON 格式返回转写文本和检测到的语言:

{
  "text": "Bonjour, pouvez-vous m'entendre ?",
  "languages": [{ "code": "fr" }]
}

如果模型无法可靠地判断语言,则返回 "languages": []。有关完整的请求和响应字段,请参阅音频 API 参考。

添加转写上下文

通过 prompt、keywords 和 languages 向 gpt-transcribe 提供信息,可提高专业术语和多语言音频的转写准确率:

添加上下文和语言提示
from openai import OpenAI

client = OpenAI()

with open("meeting.wav", "rb") as audio_file:
    transcription = client.audio.transcriptions.create(
        model="gpt-transcribe",
        file=audio_file,
        prompt="A customer support call about a premium plan and account AC-42.",
        extra_body={
            "keywords": ["premium plan", "AC-42", "billing"],
            "languages": ["en", "fr"],
        },
    )

print(transcription.text)
  • 使用 prompt 以自由文本形式提供录音的背景信息。
  • 使用 keywords 列出您预计会听到的具体词语。
  • 使用 languages 指定预期的输入语言。

关键词仅供参考,模型可根据录音内容决定是否在输出中使用。请仅列出相关词语,并评估这些关键词能否在避免引入录音中未出现的词语的同时提高准确率。

对于 gpt-transcribe,languages 取代了只接受一种语言的 language 字段。请勿同时发送这两个字段。每个关键词必须写在一行内,不能包含 <、>、回车符或换行符。如果关键词包含其中任何一个字符,或 prompt 超出模型的长度限制,API 将拒绝整个请求。

区分说话人

在 2027 年 2 月 26 日停止服务前,现有集成仍可使用已弃用的 gpt-4o-transcribe-diarize 模型,识别录音中各个片段的说话人。此模型专用于说话人标注,不建议用于常规文件转写。

请求 diarized_json 响应格式即可获得带有 speaker、start 和 end 元数据的片段。对于时长超过 30 秒的音频,请将 chunking_strategy 设为 "auto" 或语音活动检测配置。

您还可以通过 known_speaker_names[] 和 known_speaker_references[] 提供最多 4 段简短的参考音频,将片段与已知说话人对应起来。每段参考音频的时长应为 2 至 10 秒,可使用上传主音频时支持的任意输入格式。使用多部分表单数据时,请将参考片段编码为数据 URL。

标注会议录音中的说话人
import base64
from openai import OpenAI

client = OpenAI()


def to_data_url(path: str) -> str:
    with open(path, "rb") as fh:
        return "data:audio/wav;base64," + base64.b64encode(fh.read()).decode("utf-8")


with open("meeting.wav", "rb") as audio_file:
    transcript = client.audio.transcriptions.create(
        model="gpt-4o-transcribe-diarize",
        file=audio_file,
        response_format="diarized_json",
        chunking_strategy="auto",
        extra_body={
            "known_speaker_names": ["agent"],
            "known_speaker_references": [to_data_url("agent.wav")],
        },
    )

for segment in transcript.segments:
    print(segment.speaker, segment.text, segment.start, segment.end)

设置 stream=true 后,对于带说话人标注的响应,每完成一个片段,模型就会发送一个 transcript.text.segment 事件。transcript.text.delta 事件包含 segment_id 字段,但这些增量事件不包含临时的说话人标注。模型只在片段定稿时标注说话人。

/v1/audio/transcriptions 支持说话人标注。实时转写会话不支持此功能。

翻译

已弃用的 /v1/audio/translations 端点使用 whisper-1 将已完成的录音翻译成英语。此端点将在 2027 年 2 月 26 日停止服务。转写会保留录音的原始语言。此端点仅返回英文文本。

请迁移到实时翻译,使用 gpt-realtime-translate 模型和 /v1/realtime/translations 端点。您需要创建翻译会话、以流式方式输入音频并处理翻译事件。仅更改 /v1/audio/translations 请求中的模型 ID 无法完成迁移。

支持的语言

如果您知道音频中预计会出现哪些语言,请通过 languages 为 gpt-transcribe 指定这些语言。支持的语言代码格式包括:

  • ISO 639-1 代码,例如 en、es 和 fr。
  • 部分 ISO 639-3 代码,例如 eng、spa、yue 和 cmn。
  • 带地区标识的 zh 语言区域代码,例如 zh-cn、zh-tw 和 zh-hk。

API 会拒绝不受支持或格式错误的语言代码。响应还会列出模型能够可靠检测到的语言。

对于 whisper-1,请参阅 Whisper 语言列表。Whisper 支持 98 种语言,但准确率因语言而异。只接受一种语言提示的现有模型使用 language,而非 languages。

时间戳

在 2027 年 2 月 26 日停止服务前,现有集成仍可使用已弃用的 whisper-1 模型获取词级或片段级时间戳。使用 timestamp_granularities[] 参数可获取结构化的时间戳数据,用于制作字幕和剪辑视频。

时间戳选项
from openai import OpenAI

client = OpenAI()
audio_file = open("speech.wav", "rb")

transcription = client.audio.transcriptions.create(
    file=audio_file,
    model="whisper-1",
    response_format="verbose_json",
    timestamp_granularities=["word"],
)

print(transcription.words)

timestamp_granularities[] 参数仅适用于 whisper-1。

处理较长的音频

转写 API 接受最大 25 MB 的文件。对于更大的录音文件,请使用压缩音频格式,或将文件拆分为多个不超过 25 MB 的片段。请避免在句子中间切分,以免丢失上下文,降低准确率。

Python 示例使用 pydub 包拆分音频。

拆分较长的音频文件
from pydub import AudioSegment

song = AudioSegment.from_wav("good_morning.wav")

# PyDub handles time in milliseconds
ten_minutes = 10 * 60 * 1000

first_10_minutes = song[:ten_minutes]

first_10_minutes.export("good_morning_10.wav", format="wav")

OpenAI 对 pydub 和 ffmpeg 等第三方工具的可用性或安全性不作任何保证。

使用提示词

使用提示词可以帮助模型更准确地识别名称、缩略词和录音中的特定词汇,并按预期格式输出。使用 gpt-transcribe 时,请将提示词与 keywords 和 languages 结合使用,具体请参阅添加转写上下文。

使用 gpt-4o-transcribe 和 gpt-4o-mini-transcribe 的现有集成也支持提示词。gpt-4o-transcribe-diarize 不支持提示词。

提示词适用于以下场景:

  • 正确转写产品名称、技术术语和缩略词。
  • 分段转写较长的录音时,沿用上一段的上下文。
  • 保留标点、大小写和口语中的填充词。
  • 为某种语言指定首选书写系统。

对于 whisper-1,提示词最多可包含 224 个 Token,对转写结果的控制也比推荐的转写模型更有限。如果您的工作流需要使用 Whisper,请参阅提高可靠性。

流式转写

模型在处理已完成的录音时,可以以流式方式逐步返回转写文本。此操作无需创建实时会话。

以流式方式转写已完成的录音

使用 gpt-transcribe 时,设置 stream=true。模型每转写一部分录音,转写 API 就会返回相应的转写事件。

流式转写
from openai import OpenAI

client = OpenAI()
audio_file = open("speech.wav", "rb")

stream = client.audio.transcriptions.create(
    model="gpt-transcribe",
    file=audio_file,
    stream=True,
)

for event in stream:
    print(event)

模型在转写音频时会发送 transcript.text.delta 事件,随后在最终的 transcript.text.done 事件中返回完整的转写文本。如果您使用 response_format="diarized_json" 获取带说话人标注的转写结果,说话人区分模型还会在每个片段定稿时发送一个 transcript.text.segment 事件。

对于 gpt-transcribe,最终事件还包含检测到的语言:

{
  "type": "transcript.text.done",
  "text": "Bonjour, pouvez-vous m'entendre ?",
  "languages": [{ "code": "fr" }]
}

使用 gpt-4o-transcribe、gpt-4o-mini-transcribe 和 gpt-4o-transcribe-diarize 的现有集成也支持以流式方式转写文件。whisper-1 不支持此功能。

以流式方式转写正在录制的音频

对于来自麦克风、通话或媒体流的实时音频,请按实时转写指南操作。上文的流式转写流程适用于文件。该指南介绍了当前的转写会话流程,以及使用 gpt-live-transcribe 进行实时转写的推荐方式。

提高可靠性

如果您使用 whisper-1 获取时间戳、生成字幕或翻译录音,以下方法可以提高生僻词和缩略词的识别准确率。对于新的通用转写任务,请先使用 gpt-transcribe,并提供转写上下文。