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 欄位。請勿同時傳送這兩個欄位。每個關鍵字都必須維持在同一行，且不得包含 <、>、歸位字元或換行字元。當 API 遇到其中任一字元，或 prompt 超過模型的長度限制時，會拒絕整個請求。

說話者分離

只有在需要辨識錄音各個部分由誰發言時，才使用 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[] 參數。

較長的輸入

Transcriptions 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，請參閱提高可靠性。

串流轉錄

檔案轉錄可在模型處理已完成的錄音時，以串流方式傳回部分文字。這不需要建立 Realtime 工作階段。

串流傳回已完成錄音的轉錄結果

使用 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 並提供轉錄上下文。