Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

TTS-API: Puheen tuottaminen

Oppitunti 10 / 18 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. TTS-API: Puheen tuottaminen
  2. Ensimmäinen TTS-kutsusi
  3. Käytettävissä olevat mallit
  4. Tulostusmuodot
  5. Äänen tuottaminen erissä
  6. Merkkirajoitus ja jakaminen
  7. 6. tammikuuta 2027 jälkeen: Realtime-mallin puhuttaminen
  8. Keskeiset asiat

Päivitys 2. marraskuuta 2026 — Äänimallit. Useat tämän kurssin malleista on vanhentunut: tts-1, tts-1-hd ja gpt-4o-mini-tts poistuvat käytöstä 6. tammikuuta 2027 (korvaaja: gpt-realtime-2.1-mini, jonka OpenAI:n TTS-opas ilmoittaa ei tukevan päätepistettä /v1/audio/speech: puheensynteesin siirtyminen tapahtuu Realtime API:n kautta); gpt-realtime, gpt-4o-realtime ja vanhat äänimallit 20. tammikuuta 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe ja /v1/audio/translations 26. helmikuuta 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Täysdupleksista ääntä varten GPT-Live 1 on ollut saatavilla API:ssa 10. syyskuuta 2026 lähtien. Tuntia korjattu 3. marraskuuta 2026: response.stream_to_file() metodin käyttö speech.create()-tulokselle on vanhentunut SDK:ssa (“Vian vuoksi tämä metodi ei itse asiassa suoratoista”) → käytä with_streaming_response-metodia virallisen oppaan mukaisesti; malleja ja ääniä päivitetty (gpt-4o-mini-tts ja sen ääniohjeet, 13 ääntä mukaan lukien marin ja cedar); uusi osio siirtymisestä malliin gpt-realtime-2.1-mini ennen 6. tammikuuta 2027 perustuen Realtime conversations -oppaaseen. Lähteet: Text to speech · Create speech · Realtime conversations · Deprecations.

TTS-API: Puheen tuottaminen

OpenAI:n Text-to-Speech (TTS) -API muuntaa tekstin korkealaatuiseksi ääneksi. Toisin kuin Realtime API, joka hallitsee kokonaisia äänikeskusteluja, TTS-API on kertaluonteinen palvelu: lähetät tekstiä ja vastaanotat äänitiedoston. Se on ihanteellinen työkalu kuulutusten, ääni-ilmoitusten, äänikirjojen tai saavutettavan sisällön tuottamiseen.

Ensimmäinen TTS-kutsusi

Puheen tuottaminen on huomattavan yksinkertaista:

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="Tervetuloa Corsen Academyyn. "
          "Koulutuksesi ääniagenteista alkaa nyt.",
    instructions="Puhu lämpimällä ja mitatulla sävyllä.",
) as response:
    response.stream_to_file(speech_file)

API palauttaa äänivirran, jonka voit joko tallentaa suoraan tai suoratoistaa soittimeen. Käytä with_streaming_response-metodia kuten tässä esitetään: metodin stream_to_file() kutsuminen tavallisen speech.create()-tuloksen päällä on vanhentunut SDK:ssa, joka huomauttaa, ettei se itse asiassa suoratoista ääntä.

Käytettävissä olevat mallit

Kolme Audio API -mallia on vanhentunut ja ne poistuvat käytöstä 6. tammikuuta 2027: tämä on siirtymäkausi, jonka aikana niitä voi vielä käyttää.

MalliErityispiirreÄänet
gpt-4o-mini-ttsHyväksyy ohjeet: aksentti, tunne, intonaatio, nopeus, sävy, kuiskaus13 ääntä, mukaan lukien marin ja cedar, suositeltu laadun vuoksi
tts-1Matalampi viive, heikompi laatu9 ääntä: alloy, ash, coral, echo, fable, onyx, nova, sage, shimmer
tts-1-hdKorkeampi laatu kuin tts-1, suurempi viiveSamat 9 ääntä

Ohjeet eivät toimi malleilla tts-1 ja tts-1-hd. Parametri speed, arvoilla 0,25–4,0, säätää nopeutta kaikilla malleilla. Oppaan mukaan äänet on optimoitu englannille: kuuntele niitä ranskaksi osoitteessa OpenAI.fm ennen valintaa. OpenAI:n käyttöehdot vaativat myös, että ilmoitat käyttäjillesi selkeästi kuulevansa tekoälyn tuottaman äänen.

Tulostusmuodot

API tuottaa kuusi muotoa, jotka valitaan parametrilla response_format:

MuotoKäyttö
mp3 (oletus)Yleiskäyttö
opusInternet-suoratoisto ja viestintä, matala viive
aacDigitaalinen pakkaus, YouTube, Android ja iOS suosivat
flacHäviötön pakkaus, arkistointiin
wavPakkaamaton, välttää purkuviiveen
pcmRaakatiedot 24 kHz, 16-bittinen etumerkillinen, ei otsikkoa
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="Muunnettava teksti",
        response_format=fmt,
    ) as response:
        response.stream_to_file(f"example.{fmt}")

Realtime API:hun perustuvalle ääniagentille muoto pcm on kätevin: sen 24 kHz, 16-bittiset näytteet vastaavat Realtime API:n audio/pcm-muotoa taajuudella 24 kHz.

Äänen tuottaminen erissä

Suurille tekstivolyymeille käsittele segmentit rinnakkain:

import asyncio
from openai import AsyncOpenAI

async_client = AsyncOpenAI()

async def generate_speech_batch(segments: list[dict]) -> list[bytes]:
    """Tuota ääni useille segmenteille rinnakkain."""
    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)

# Käyttö
segments = [
    {"text": "Luku yksi. Johdanto ääniagentteihin.", "voice": "onyx"},
    {"text": "Ääniagentit muuttavat ihmisen ja tietokoneen välistä vuorovaikutusta.", "voice": "onyx"},
    {"text": "Tässä luvussa tutkimme perusteita.", "voice": "onyx"},
]

audio_chunks = asyncio.run(generate_speech_batch(segments))

# Yhdistä tiedostot
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")

Merkkirajoitus ja jakaminen

TTS-API:ssa on raja 4 096 merkkiä pyyntöä kohden. Pidemmille teksteille jaa ne älykkäästi:

def split_text_for_tts(text: str, max_chars: int = 4000) -> list[str]:
    """Jaa teksti segmentteihin kunnioittaen TTS-rajoituksia."""
    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

6. tammikuuta 2027 jälkeen: Realtime-mallin puhuttaminen

OpenAI nimeää gpt-realtime-2.1-mini:n korvaajaksi kolmelle mallille ja varoittaa: se ei ole malli päätepisteelle /v1/audio/speech; migraatio muuttaa työkulkua. Siirryt Realtime-istunnon kautta. Realtime conversations -opas näyttää, miten saada vastaus ilman kontekstia, mikä ignoroi keskustelun ja seuraa vain sen ohjeita: näin saat sen sanomaan annetun tekstin.

import base64
import json
import os
import wave

import websocket  # pip install websocket-client

TEXT = "Tervetuloa Corsen Academyyn. Koulutuksesi ääniagenteista alkaa nyt."

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']}"],
)

# Vain äänilähtö, 16-bittinen PCM 24 kHz, valitulla äänellä
ws.send(json.dumps({
    "type": "session.update",
    "session": {
        "type": "realtime",
        "output_modalities": ["audio"],
        "audio": {"output": {"format": {"type": "audio/pcm", "rate": 24000}, "voice": "marin"}},
    },
}))

# Kontekstiton vastaus (tyhjä syöte), jonka tulee sanoa teksti sellaisenaan
ws.send(json.dumps({
    "type": "response.create",
    "response": {
        "input": [],
        "output_modalities": ["audio"],
        "instructions": f"Sano tarkasti seuraava teksti lisäämättä mitään:\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 bittiä
    wav.setframerate(24000)
    wav.writeframes(bytes(audio))
print("Puhuttu teksti:", "".join(transcription))

Kaksi eroa Audio API:hun ovat merkittäviä tuotannossa. Tulosta ei enää taata sanasta sanaan: Realtime-malli seuraa ohjetta; se ei lue tiedostoa. Vertaa siis sen puhuman tekstin transkriptiota, joka palautetaan kohdassa response.output_audio_transcript.delta, odotettuun tekstiin ja generoi uudelleen, jos on epäsuhta. Laskutus muuttuu myös: se seuraa Realtime-mallin hintoja teksti- ja äänitokeneissa, jotka on lueteltu sen tekniset tiedot -sivulla. Lopuksi, hylätty avain ei estä yhteyden muodostamista: se saapuu vasta sen jälkeen error-tapahtumana.

Keskeiset asiat

  • gpt-4o-mini-tts, tts-1 ja tts-1-hd poistuvat käytöstä 6. tammikuuta 2027; gpt-4o-mini-tts on ainoa, joka hyväksyy ääniohjeet (instructions)
  • Tallenna ääni käyttämällä with_streaming_response: stream_to_file() tavalliselle speech.create()-tulokselle on vanhentunut
  • Kuusi tulostusmuotoa: MP3, Opus, AAC, FLAC, WAV ja raaka PCM
  • PCM-muoto on ihanteellinen integrointiin Realtime API:n kanssa
  • 4 096 merkin raja pyyntöä kohden: jaa pitkät tekstit lauseiden rajoista
  • Eräkäsittely asynkronisella asiakkaalla nopeuttaa suurten sisältöjen tuottamista
  • Migraatio tapahtuu Realtime-istunnon kautta mallilla gpt-realtime-2.1-mini: kontekstiton vastaus, 24 kHz PCM-ääni, transkriptio vertailtavaksi tekstiin