Przejdź do głównej treści
Polski— Wybierz język
Menu

API TTS: Generowanie mowy

Lekcja 10 z 18 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. API TTS: Generowanie mowy
  2. Twoje pierwsze wywołanie TTS
  3. Dostępne modele
  4. Formaty wyjściowe
  5. Generowanie audio wsadowo
  6. Limit znaków i dzielenie
  7. Po 6 stycznia 2027 r.: Jak sprawić, by model Realtime mówił
  8. Kluczowe wnioski

Aktualizacja z 2 listopada 2026 — Modele audio. Kilka modeli w tym kursie jest przestarzałych: tts-1, tts-1-hd oraz gpt-4o-mini-tts zostaną 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-realtime oraz 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-transcribe oraz /v1/audio/translations zostaną 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 wyniku speech.create() jest przestarzałe w SDK („Z powodu błędu metoda ta faktycznie nie strumieniuje“) → użyj with_streaming_response, jak w oficjalnym przewodniku; zaktualizowano modele i głosy (gpt-4o-mini-tts i jego instrukcje głosowe, 13 głosów, w tym marin i cedar); dodano nową sekcję dotyczącą migracji na gpt-realtime-2.1-mini przed 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ć.

ModelSpecyfikaGłosy
gpt-4o-mini-ttsAkceptuje instrukcje: akcent, emocje, intonacja, szybkość, ton, szept13 głosów, w tym marin i cedar, zalecane ze względu na jakość
tts-1Mniejsze opóźnienia, niższa jakość9 głosów: alloy, ash, coral, echo, fable, onyx, nova, sage, shimmer
tts-1-hdWyższa jakość niż tts-1, większe opóźnieniaTe 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:

FormatZastosowanie
mp3 (domyślny)Ogólne zastosowanie
opusStrumieniowanie internetowe i komunikacja, niskie opóźnienia
aacKompresja cyfrowa, preferowane przez YouTube, Androida i iOS
flacKompresja bezstratna, do archiwizacji
wavNieskompresowane, aby uniknąć narzutu dekodowania
pcmSurowe 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-1 i tts-1-hd zostaną wyłączone 6 stycznia 2027 r.; gpt-4o-mini-tts jest jedynym modelem akceptującym instrukcje głosowe (instructions)
  • Nagrywaj audio za pomocą with_streaming_response: stream_to_file() na zwykłym speech.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