API TTS: Generowanie mowy
Na tej stronie
Aktualizacja z 2 listopada 2026 — Modele audio. Kilka modeli w tym kursie jest przestarzałych:
tts-1,tts-1-hdorazgpt-4o-mini-ttszostaną wyłączone 6 stycznia 2027 r. (następca:gpt-realtime-2.1-mini, który zgodnie z przewodnikiem OpenAI TTS nie jest obsługiwany przez/v1/audio/speech: migracja syntezy mowy przechodzi do API Realtime);gpt-realtime,gpt-4o-realtimeoraz starsze modele audio zostaną wyłączone 20 stycznia 2027 r. (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribeoraz/v1/audio/translationszostaną wyłączone 26 lutego 2027 r. (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). W przypadku komunikacji głosowej full-duplex, GPT-Live 1 jest dostępny w API od 10 września 2026 r. Lekcja poprawiona 3 listopada 2026 r.:response.stream_to_file()na wynikuspeech.create()jest przestarzałe w SDK („Z powodu błędu metoda ta faktycznie nie strumieniuje“) → użyjwith_streaming_response, jak w oficjalnym przewodniku; zaktualizowano modele i głosy (gpt-4o-mini-ttsi jego instrukcje głosowe, 13 głosów, w tymmarinicedar); dodano nową sekcję dotyczącą migracji nagpt-realtime-2.1-miniprzed 6 stycznia 2027 r., opartą na przewodniku Realtime conversations. Źródła: Text to speech · Create speech · Realtime conversations · Deprecations.
API TTS: Generowanie mowy
API Text-to-Speech (TTS) firmy OpenAI konwertuje tekst na wysokiej jakości audio. W przeciwieństwie do API Realtime, które obsługuje pełne rozmowy głosowe, API TTS jest usługą jednorazową: wysyłasz tekst, a otrzymujesz plik audio. To idealne narzędzie do generowania ogłoszeń, powiadomień głosowych, audiobooków lub treści dostępnych.
Twoje pierwsze wywołanie TTS
Generowanie mowy jest niezwykle proste:
from openai import OpenAI
from pathlib import Path
client = OpenAI()
speech_file = Path("welcome.mp3")
with client.audio.speech.with_streaming_response.create(
model="gpt-4o-mini-tts",
voice="coral",
input="Witamy w Corsen Academy. "
"Twoje szkolenie z agentów głosowych zaczyna się teraz.",
instructions="Mów ciepłym, wyważonym tonem.",
) as response:
response.stream_to_file(speech_file)
API zwraca strumień audio, który możesz zapisać bezpośrednio lub przesłać strumieniowo do odtwarzacza. Użyj with_streaming_response, jak pokazano powyżej: wywołanie stream_to_file() na wyniku zwykłego speech.create() jest przestarzałe w SDK, które zauważa, że nie strumieniuje ono faktycznie audio.
Dostępne modele
Trzy modele Audio API są przestarzałe i zostaną wyłączone 6 stycznia 2027 r.: to okres przejściowy, podczas którego nadal będziesz z nich korzystać.
| Model | Specyfika | Głosy |
|---|---|---|
gpt-4o-mini-tts | Akceptuje instrukcje: akcent, emocje, intonacja, szybkość, ton, szept | 13 głosów, w tym marin i cedar, zalecane ze względu na jakość |
tts-1 | Mniejsze opóźnienia, niższa jakość | 9 głosów: alloy, ash, coral, echo, fable, onyx, nova, sage, shimmer |
tts-1-hd | Wyższa jakość niż tts-1, większe opóźnienia | Te same 9 głosów |
Instrukcje nie działają z tts-1 i tts-1-hd. Parametr speed, od 0,25 do 4,0, dostosowuje tempo we wszystkich modelach. Zgodnie z przewodnikiem głosy są zoptymalizowane pod język angielski: wysłuchaj ich po francusku na OpenAI.fm przed wyborem. Polityki użytkowania OpenAI wymagają również wyraźnego poinformowania użytkowników, że słyszany głos jest generowany przez AI.
Formaty wyjściowe
API generuje sześć formatów, wybieranych za pomocą response_format:
| Format | Zastosowanie |
|---|---|
mp3 (domyślny) | Ogólne zastosowanie |
opus | Strumieniowanie internetowe i komunikacja, niskie opóźnienia |
aac | Kompresja cyfrowa, preferowane przez YouTube, Androida i iOS |
flac | Kompresja bezstratna, do archiwizacji |
wav | Nieskompresowane, aby uniknąć narzutu dekodowania |
pcm | Surowe próbki przy 24 kHz, 16-bitowe ze znakiem, bez nagłówka |
for fmt in ("mp3", "opus", "aac", "flac", "wav", "pcm"):
with client.audio.speech.with_streaming_response.create(
model="gpt-4o-mini-tts",
voice="marin",
input="Tekst do konwersji",
response_format=fmt,
) as response:
response.stream_to_file(f"example.{fmt}")
Dla agenta głosowego opartego na API Realtime format pcm jest najwygodniejszy: jego próbki 24 kHz, 16-bitowe odpowiadają formatowi audio/pcm API Realtime przy 24 kHz.
Generowanie audio wsadowo
W przypadku dużych ilości tekstu przetwarzaj segmenty równolegle:
import asyncio
from openai import AsyncOpenAI
async_client = AsyncOpenAI()
async def generate_speech_batch(segments: list[dict]) -> list[bytes]:
"""Generuj audio dla wielu segmentów równolegle."""
async def generate_one(segment):
response = await async_client.audio.speech.create(
model="gpt-4o-mini-tts",
voice=segment.get("voice", "alloy"),
input=segment["text"],
response_format="mp3"
)
return await response.aread()
tasks = [generate_one(seg) for seg in segments]
return await asyncio.gather(*tasks)
# Użycie
segments = [
{"text": "Rozdział pierwszy. Wprowadzenie do agentów głosowych.", "voice": "onyx"},
{"text": "Agenci głosowi transformują interakcję człowiek-komputer.", "voice": "onyx"},
{"text": "W tym rozdziale zbadamy fundamenty.", "voice": "onyx"},
]
audio_chunks = asyncio.run(generate_speech_batch(segments))
# Łączenie plików
from pydub import AudioSegment
import io
combined = AudioSegment.empty()
for chunk in audio_chunks:
segment = AudioSegment.from_mp3(io.BytesIO(chunk))
combined += segment
combined.export("chapter_1.mp3", format="mp3")
Limit znaków i dzielenie
API TTS ma limit 4096 znaków na żądanie. W przypadku dłuższych tekstów dziel je inteligentnie:
def split_text_for_tts(text: str, max_chars: int = 4000) -> list[str]:
"""Podziel tekst na segmenty z poszanowaniem limitów TTS."""
sentences = text.replace(". ", ".\n").split("\n")
segments = []
current = ""
for sentence in sentences:
if len(current) + len(sentence) + 1 > max_chars:
if current:
segments.append(current.strip())
current = sentence
else:
current += " " + sentence if current else sentence
if current:
segments.append(current.strip())
return segments
Po 6 stycznia 2027 r.: Jak sprawić, by model Realtime mówił
OpenAI wyznacza gpt-realtime-2.1-mini jako zamiennik trzech modeli i ostrzega: nie jest to model dla punktu końcowego /v1/audio/speech; migracja zmienia przepływ pracy. Przechodzisz przez sesję Realtime. Przewodnik Realtime conversations pokazuje, jak uzyskać odpowiedź bez kontekstu, co ignoruje rozmowę i podąża tylko za instrukcjami: to sposób, aby zmusić model do wypowiedzenia danego tekstu.
import base64
import json
import os
import wave
import websocket # pip install websocket-client
TEXT = "Witamy w Corsen Academy. Twoje szkolenie z agentów głosowych zaczyna się teraz."
ws = websocket.WebSocket()
ws.connect(
"wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1-mini",
header=[f"Authorization: Bearer {os.environ['OPENAI_API_KEY']}"],
)
# Tylko wyjście audio, 16-bit PCM przy 24 kHz, z wybranym głosem
ws.send(json.dumps({
"type": "session.update",
"session": {
"type": "realtime",
"output_modalities": ["audio"],
"audio": {"output": {"format": {"type": "audio/pcm", "rate": 24000}, "voice": "marin"}},
},
}))
# Odpowiedź bez kontekstu (puste wejście), która musi wypowiedzieć tekst tak, jak jest
ws.send(json.dumps({
"type": "response.create",
"response": {
"input": [],
"output_modalities": ["audio"],
"instructions": f"Powiedz dokładnie następujący tekst, nic nie dodając:\n{TEXT}",
},
}))
audio, transcription = bytearray(), []
while True:
event = json.loads(ws.recv())
if event["type"] == "response.output_audio.delta":
audio += base64.b64decode(event["delta"])
elif event["type"] == "response.output_audio_transcript.delta":
transcription.append(event["delta"])
elif event["type"] == "error":
raise RuntimeError(event["error"]["message"])
elif event["type"] == "response.done":
break
ws.close()
with wave.open("welcome.wav", "wb") as wav:
wav.setnchannels(1)
wav.setsampwidth(2) # 16 bits
wav.setframerate(24000)
wav.writeframes(bytes(audio))
print("Wypowiedziany tekst:", "".join(transcription))
Dwie różnice względem Audio API mają znaczenie w produkcji. Wynik nie jest już gwarantowany słowo w słowo: model Realtime podąża za instrukcją; nie czyta pliku. Porównaj więc transkrypcję tego, co powiedział, zwróconą w response.output_audio_transcript.delta, z oczekiwanym tekstem i wygeneruj ponownie w przypadku niezgodności. Rozliczenia również się zmieniają: podlegają stawkom modelu Realtime, w tokenach tekstowych i audio, wymienionym w jego specyfikacji. Na koniec odrzucony klucz nie blokuje połączenia: pojawia się tuż po nim, w zdarzeniu error.
Kluczowe wnioski
gpt-4o-mini-tts,tts-1itts-1-hdzostaną wyłączone 6 stycznia 2027 r.;gpt-4o-mini-ttsjest jedynym modelem akceptującym instrukcje głosowe (instructions)- Nagrywaj audio za pomocą
with_streaming_response:stream_to_file()na zwykłymspeech.create()jest przestarzałe - Sześć formatów wyjściowych: MP3, Opus, AAC, FLAC, WAV i surowy PCM
- Format PCM jest idealny do integracji z API Realtime
- Limit 4096 znaków na żądanie: dziel długie teksty na granicach zdań
- Przetwarzanie wsadowe z klientem asynchronicznym przyspiesza generowanie dużych treści
- Migracja odbywa się przez sesję Realtime z
gpt-realtime-2.1-mini: odpowiedź bez kontekstu, audio PCM 24 kHz, transkrypcja do porównania z tekstem