Transkrypcja pliku audio: gpt-transcribe i Whisper
Na tej stronie
Lekcja przepisana 3 listopada 2026 r. Ten przewodnik wcześniej omawiał model
whisper-1, który jest przestarzały i zostanie wycofany 26 lutego 2027 r. Przewodnik OpenAI dotyczący transkrypcji plików obecnie rekomenduje użyciegpt-transcribe. Należy jednak pamiętać, żegpt-transcribenie udostępnia znaczników czasu, napisów w formacie SRT ani VTT, ani odpowiedzi w formacieverbose_json. Dla tych konkretnych potrzebwhisper-1pozostaje jedyną opcją aż do momentu jego wycofania. W poprzednim kodzie segmenty były obsługiwane jako słowniki (segment["start"]), co przy użyciu Python SDK powoduje błądTypeError; są to obiekty (segment.start). Każde wywołanie zostało zweryfikowane przy użyciu SDKopenaiw wersji 3.42.1. Źródła: File transcription · Create transcription · GPT-Transcribe · Deprecations.
Transkrypcja nagrania
Transkrypcja plików odpowiada najczęstszemu przypadkowi użycia: masz gotowe nagranie (spotkanie, podcast, wiadomość głosową) i potrzebujesz jego tekstu. Wysyłasz plik do punktu końcowego /v1/audio/transcriptions i otrzymujesz transkrypcję. W przypadku dźwięku, który nadal napływa, np. z mikrofonu lub podczas rozmowy, właściwym podejściem jest transkrypcja na żywo przez Realtime API, co omówimy później w tym kursie.
Plik musi mieć rozmiar 25 MB lub mniejszy i być zapisany w jednym z następujących formatów: mp3, mp4, mpeg, mpga, m4a, wav lub webm.
Który model wybrać w listopadzie 2026 r.
| Model | Status | Kluczowe cechy |
|---|---|---|
gpt-transcribe | Rekomendowany | Kontekst (prompt), słowa kluczowe (keywords), oczekiwane języki (languages), transkrypcja strumieniowa; 0,0045 USD za minutę |
whisper-1 | Przestarzały, wycofanie 26 lutego 2027 r. | Jedyny model udostępniający znaczniki czasu, verbose_json, napisy SRT i VTT oraz tłumaczenie na język angielski |
gpt-4o-transcribe, gpt-4o-mini-transcribe | Przestarzały, wycofanie 26 lutego 2027 r. | Zastąpiony przez gpt-transcribe |
gpt-4o-transcribe-diarize | Przestarzały, wycofanie 26 lutego 2027 r. | Identyfikacja mówcy (diarized_json) |
Pierwsza transkrypcja
from openai import OpenAI
client = OpenAI()
with open("recording.mp3", "rb") as audio_file:
transcription = client.audio.transcriptions.create(
model="gpt-transcribe",
file=audio_file,
)
print(transcription.text)
Domyślnie odpowiedź jest obiektem JSON: transcription.text zawiera tekst, a transcription.languages wymienia języki, które model rozpoznał z wystarczającym poziomem pewności (pusta lista, jeśli nie udało się zidentyfikować żadnego).
Nadaj modelowi kontekst
Nagranie ze spotkania jest pełne nazw własnych, akronimów i terminów wewnętrznych, których model nie ma powodu znać. gpt-transcribe akceptuje trzy wskazówki, które możesz łączyć:
with open("meeting.mp3", "rb") as audio_file:
transcription = client.audio.transcriptions.create(
model="gpt-transcribe",
file=audio_file,
prompt="Spotkanie zarządu dotyczące projektu Corsen AI i kontraktu AC-42.",
keywords=["Corsen AI", "AC-42", "RODO"],
languages=["pl", "en"],
)
print(transcription.text)
promptopisuje kontekst w jednym zdaniu, w języku nagrania. Nie jest to instrukcja systemowa, lecz wskazówka kierująca rozpoznawaniem.keywordsto lista terminów do rozpoznania. Wpisz jedno słowo kluczowe na element, bez znaków<,>lub znaków nowej linii: API odrzuci całe żądanie, jeśli znajdzie którykolwiek z nich.languagesokreśla oczekiwane języki przy użyciu kodów ISO 639-1 (pl,en,es…). Zastępuje to parametrlanguageze starszych modeli: nigdy nie wysyłaj obu jednocześnie.
Śledź transkrypcję w czasie rzeczywistym
W przypadku długich plików nie musisz czekać do końca, aby wyświetlić początek. Dzięki stream=True API zwraca zdarzenia w miarę przetwarzania, bez konieczności inicjowania sesji Realtime:
with open("meeting.mp3", "rb") as audio_file:
stream = client.audio.transcriptions.create(
model="gpt-transcribe",
file=audio_file,
stream=True,
)
for event in stream:
if event.type == "transcript.text.delta":
print(event.delta, end="", flush=True)
elif event.type == "transcript.text.done":
print() # pełna transkrypcja w event.text
Znaczniki czasu i napisy: whisper-1 do 26 lutego 2027 r.
Przewodnik OpenAI stwierdza wyraźnie: jego przykłady dotyczące znaczników czasu na poziomie wyrazów, napisów i identyfikacji mówcy opierają się na przestarzałych modelach. Jeśli potrzebujesz tych funkcji, whisper-1 pozostaje dostępny do 26 lutego 2027 r. i jest to jedyny model akceptujący verbose_json oraz timestamp_granularities:
with open("meeting.mp3", "rb") as audio_file:
transcription = client.audio.transcriptions.create(
model="whisper-1",
file=audio_file,
response_format="verbose_json",
timestamp_granularities=["segment"],
)
for segment in transcription.segments or []:
print(f"[{segment.start:.1f}s - {segment.end:.1f}s] {segment.text.strip()}")
Segmenty są obiektami SDK: odczytuj segment.start, a nie segment["start"]. Przy użyciu timestamp_granularities=["word"] znaczniki czasu na poziomie wyrazów pojawiają się w transcription.words, kosztem nieco większego opóźnienia. Ten sam model generuje również gotowe do użycia napisy: przy response_format="srt" lub "vtt" SDK zwraca bezpośrednio tekst pliku z napisami.
Przewodnik nie wskazuje jeszcze zamiennika dla tych funkcji. Jeśli Twój produkt zależy od znaczników czasu lub napisów, zaplanuj rozwiązanie przed 26 lutego 2027 r.
Długie pliki
W przypadku plików większych niż 25 MB skompresuj dźwięk lub podziel go. Dokumentacja zaleca unikanie cięć w środku zdania, co powoduje utratę kontekstu, i sugeruje bibliotekę pydub do dzielenia (OpenAI nie gwarantuje działania tego oprogramowania firm trzecich). Przekazanie końca poprzedniego fragmentu w parametrze prompt pomaga modelowi zachować ciągłość – jest to zastosowanie tego parametru cytowane w przewodniku:
from pydub import AudioSegment
def transcribe_long(path: str, duration_ms: int = 10 * 60 * 1000) -> str:
"""Transkrybuje długie nagranie w 10-minutowych fragmentach."""
audio = AudioSegment.from_file(path)
texts: list[str] = []
for i, start in enumerate(range(0, len(audio), duration_ms)):
chunk = f"chunk_{i}.mp3"
audio[start:start + duration_ms].export(chunk, format="mp3")
options = {"prompt": texts[-1][-500:]} if texts else {} # ciągłość
with open(chunk, "rb") as f:
result = client.audio.transcriptions.create(model="gpt-transcribe", file=f, **options)
texts.append(result.text)
return " ".join(texts)
Dzielenie o stałym czasie trwania czasami przecina zdanie w połowie: aby uzyskać dopracowany wynik, dziel nagranie w miejscach ciszy.
Kluczowe wnioski
gpt-transcribeto rekomendowany model do transkrypcji plików;whisper-1orazgpt-4o-*-transcribezostaną wycofane 26 lutego 2027 r.- Parametry
prompt,keywordsilanguages(zamiast dawnegolanguage) kierują rozpoznawaniem terminów i języków. stream=Truezwraca transkrypcję na bieżąco (transcript.text.delta) bez konieczności uruchamiania sesji Realtime.- Znaczniki czasu,
verbose_json, SRT i VTT są dostępne wyłącznie w modeluwhisper-1do momentu jego wycofania; odczytuj segmenty jako obiekty (segment.start). - Maksymalny rozmiar pliku to 25 MB: skompresuj go lub podziel, najlepiej w miejscach ciszy.