For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
主导航

建议

GPT-Live

Realtime API

构建语音应用

连接

音频处理

API Dashboard
试用 ChatGPT

文件转录

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

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

首先使用 gpt-transcribe。这是按录音原始语言转录语音的推荐模型。只有在需要说话人标签、词级时间戳、字幕格式或翻译成英语时，才使用专用模型。

文件大小上限为 25 MB。支持的输入格式包括 mp3、mp4、mpeg、mpga、m4a、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 参考。

添加转录上下文

使用 gpt-transcribe 时，配合使用 prompt、keywords 和 languages，以改善领域术语和多语言音频的转录效果：

添加上下文和语言提示
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 会拒绝整个请求。

说话人分离

只有在需要识别录音中不同片段的说话人时，才使用 gpt-4o-transcribe-diarize。对于普通文件转录，不推荐使用这一专门用于说话人标注的模型。

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

您还可以通过 known_speaker_names[] 和 known_speaker_references[] 提供最多四段简短的参考音频，将片段对应到已知说话人。参考片段时长应为 2–10 秒，可使用主音频上传所支持的任意输入格式；使用多部分表单数据时，请将其编码为 data 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。转录会保留录音的原始语言，而此端点返回英语文本。

翻译音频
from openai import OpenAI

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

translation = client.audio.translations.create(
    model="whisper-1",
    file=audio_file,
)

print(translation.text)

对于其他语言的录音，响应包含英语译文：

Hello, my name is Wolfgang and I come from Germany. Where are you heading today?

此端点仅支持翻译成英语。

支持的语言

如果您知道预期的输入语言，请在使用 gpt-transcribe 时配合使用 languages。支持的语言代码格式包括：

  • 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。

时间戳

如果您需要词级或片段级时间戳，请使用 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)

仅 whisper-1 支持 timestamp_granularities[] 参数。

更长的输入

转录 API 接受的文件大小上限为 25 MB。对于更大的录音文件，请使用压缩音频格式，或将文件拆分为不超过 25 MB 的片段。避免在句子中间拆分，否则可能丢失上下文并降低准确率。

一种处理方法是使用 PyDub 开源 Python 包拆分音频：

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 等第三方软件的可用性或安全性作任何保证。

提示词

使用提示可以改善对名称、首字母缩略词、格式或录音中特有词汇的识别。使用 gpt-transcribe 时，请将提示与添加转录上下文中介绍的 keywords 和 languages 配合使用。

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

适合使用提示的场景包括：

  • 准确转录产品名称、技术术语和首字母缩略词。
  • 沿用较长录音中上一个片段的上下文。
  • 保留标点符号、大小写和语气填充词。
  • 为某种语言选择首选的书写系统。

whisper-1 的提示长度上限为 224 个 Token，且对转录结果的控制能力不及推荐的转录模型。如果您的工作流程需要使用 Whisper，请参阅提高可靠性。

流式转录

文件转录可以在模型处理已录制完成的音频时，以流式方式返回部分文本。此过程无需实时会话。

以流式方式转录已录制完成的音频

使用 gpt-transcribe 时，设置 stream=true。模型逐段转录录音时，Transcriptions 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 入手，改用转录上下文。