如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .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[] 提供最多四段簡短的參考音訊,將各片段對應到已知的說話者。每段參考音訊的長度須為 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 的片段。請避免在句子中間分割,以免遺失上下文而降低準確度。

你可以使用 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,請參閱提高可靠性。

串流轉錄

使用檔案轉錄時,模型可以一邊處理已完成的錄音,一邊串流傳回已轉錄的文字。這不需要建立即時工作階段。

串流接收已完成錄音的轉錄文字

將 stream=true 與 gpt-transcribe 搭配使用。模型逐段轉錄錄音時,轉錄 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 並提供轉錄上下文。