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

Automaattinen kääntäminen

Oppitunti 8 / 18 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Kaksi tarvetta, kaksi työkalua
  2. Nauhoituksen kääntäminen
  3. Elävän puheen tulkitseminen
  4. Keskeiset asiat

Oppitunti kirjoitettu uudelleen 3. marraskuuta 2026. Aiemmin se perustui /v1/audio/translations-päätepisteeseen ja whisper-1-malliin, jotka molemmat on merkitty vanhentuneiksi ja poistettu käytöstä 26. helmikuuta 2027, sekä uudelleenkäytettyyn Realtime-avustajaseanssiin tulkkina. OpenAI tarjoaa nyt kaksi polkua: nauhoituksille alkuperäisen kielen litterointi mallilla gpt-transcribe, jota seuraa tekstin kääntäminen; elävälle puheelle omistettu käännösseanssi mallilla gpt-realtime-translate. Koodi on testattu SDK:n openai versiolla 3.42.1 ja websocket-client-kirjastolla. Lähteet: Tiedostolitterointi · Realtime-kääntäminen · Vanhentumiset.

Kaksi tarvetta, kaksi työkalua

Äänen kääntäminen kattaa kaksi hyvin erilaista skenaariota, ja OpenAI hoitaa ne eri työkaluilla:

TarveTyökalu marraskuusta 2026 alkaenTulos
Nauhoitus käännettäväksi (kokous, podcasti, arkistoitu puhelu)gpt-transcribe litteroimaan alkuperäisellä kielellä, sitten tekstimalleilla kääntäminenKäännetty teksti kohdekielelläsi
Elävä puhe tulkattavaksi (puhelu, konferenssi, oppitunti)Käännösseanssi mallilla gpt-realtime-translateKäännetty ääni ja litteroinnit, tuotettu puheen edetessä
Vanha polku: /v1/audio/translations mallilla whisper-1Vanhentunut, poistettu käytöstä 26. helmikuuta 2027Vain englanninkielinen teksti

OpenAI:n ohje korostaa yhtä seikkaa: pelkkä mallitunnuksen vaihtaminen /v1/audio/translations-pyynnössä ei siirrä mitään. Vanhalla päätepisteellä, joka pystyi kääntämään vain englanniksi, ei ole suoraa korvaajaa.

Nauhoituksen kääntäminen

Tämä menetelmä litteroi ensin uskollisesti puhutulla kielellä ja kääntää sitten tekstin. Se toimii mille tahansa kohdekielelle – toisin kuin vanha päätepiste, joka tuotti vain englantia – ja antaa sinulle molemmat tekstit, mikä on hyödyllistä tarkistusta varten:

from openai import OpenAI

client = OpenAI()


def translate_recording(path: str, target_language: str) -> dict[str, str]:
    """Litteroi nauhoituksen alkuperäisellä kielellä ja kääntää sitten tekstin."""
    with open(path, "rb") as f:
        transcription = client.audio.transcriptions.create(model="gpt-transcribe", file=f)

    response = client.responses.create(
        model="gpt-6-luna",
        instructions=(
            f"Käännä käyttäjän toimittama teksti kielelle {target_language}. "
            "Säilytä sävy ja tyyli. Vastaa vain käännöksellä."
        ),
        input=transcription.text,
    )
    return {"original": transcription.text, "translation": response.output_text}


result = translate_recording("reunion_fr.mp3", "German")
print(result["translation"])

Kaksi valintaa ansaitsee selityksen. Käännösohje menee kenttään instructions, kun taas litterointi saapuu raakadatana kentässä input: nauhoitus voi sisältää mitä tahansa, myös lauseen, joka näyttää komennolta, eikä sen saa pystyä muuttamaan ohjetta. Malli gpt-6-luna on OpenAI:n suositus laajamittaiseen, kustannusherkkään käsittelyyn; arkaluonteiselle juridiseen tai tekniseen tekstiin valitse kyvykkäämpi malli, kuten gpt-6.1-sol.

Elävän puheen tulkitseminen

Kääntääksesi samalla kun joku puhuu, OpenAI tarjoaa erityisen tyyppisen Realtime-seanssin. Ohje erottaa sen selvästi puheagenttiseanssista:

PuheagenttiseanssiKäännösseanssi
Yhdistää osoitteeseen /v1/realtimeYhdistää osoitteeseen /v1/realtime/translations
Malli toimii avustajanaMalli toimii tulkkina
Keskustelu- ja vastussykli (response.create)Jatkuva virta saapuvasta äänestä, ei response.create-komentoa
Voi kutsua työkalujaTuottaa käännettyä ääntä ja litterointeja

Kuljetus riippuu siitä, mihin ääni saapuu. Selaimessa WebRTC lähettää mikrofonisyötteen ja vastaanottaa käännetyn äänen ääniraitoina; palvelimesi luo tätä varten lyhytikäisen asiakassalaisuuden osoitteessa /v1/realtime/translations/client_secrets, jotta API-avaimesi ei koskaan poistu palvelimelta. Palvelinpuolella, kun ääni saapuu jo raakana (puheluvirta, kaappaus), WebSocket-yhteys riittää:

import base64
import json
import os

import websocket  # pip install websocket-client

ws = websocket.WebSocket()
ws.connect(
    "wss://api.openai.com/v1/realtime/translations?model=gpt-realtime-translate",
    header=[
        f"Authorization: Bearer {os.environ['OPENAI_API_KEY']}",
        "OpenAI-Safety-Identifier: hashed-user-id",  # käyttäjäsi hashattu tunniste
    ],
)

# Tulkin tulostuskieli
ws.send(json.dumps({"type": "session.update", "session": {"audio": {"output": {"language": "en"}}}}))


def send_audio(pcm16: bytes) -> None:
    """Lisää palan lähdeääntä: 16-bittinen PCM, mono, 24 kHz."""
    ws.send(json.dumps({"type": "session.input_audio_buffer.append", "audio": base64.b64encode(pcm16).decode()}))

Kun lähetät ääntä, hiljaisuudet mukaan lukien, seanssi palauttaa tapahtumia käsiteltäväksi reaaliajassa: session.output_audio.delta sisältää käännetyn äänen base64-muodossa, session.output_transcript.delta käännetyn tekstin ja session.input_transcript.delta alkuperäisen litteroinnin. Kun lähde pysähtyy, lähetä session.close: palvelu viimeistelee nykyisen käännöksen ja vastaa sitten tapahtumalla session.closed.

translation: list[str] = []
while True:
    event = json.loads(ws.recv())
    if event["type"] == "session.output_transcript.delta":
        translation.append(event["delta"])
    elif event["type"] == "error":
        raise RuntimeError(f"Käännösvirhe: {event['error']['code']}")
    elif event["type"] == "session.closed":
        break
ws.close()
print("".join(translation))

Älä laiminlyö error-tapahtumaa: hylätty avain ei kaada itse yhteyttä; se saapuu heti sen jälkeen error-tapahtumana, jonka koodi on invalid_api_key (havaittu 3. marraskuuta 2026). Tuotannossa vastaanotto ajetaan rinnakkain lähetyksen kanssa erillisessä säikeessä tai tehtävässä, ja käännetty ääni ohjataan soittimeen tai puhelulinjaan sitä mukaa kun se saapuu: virallinen ohje tarjoaa täydellisen version, mukaan lukien äänen toisto.

Keskeiset asiat

  • /v1/audio/translations ja whisper-1 suljetaan 26. helmikuuta 2027 ilman suoraa korvaajaa: pelkkä mallin vaihtaminen ei riitä
  • Nauhoitukselle: gpt-transcribe alkuperäisellä kielellä, sitten tekstin kääntäminen tekstimalleilla mihin tahansa kieleen
  • Pidä käännösohje kentässä instructions ja litterointi raakadatana
  • Elävälle puheelle: käännösseanssi (/v1/realtime/translations, gpt-realtime-translate), joka toimii tulkkina ilman response.create-komentoa
  • WebRTC selaimessa palvelimen luomalla asiakassalaisuudella; WebSocket palvelinpuolella 16-bittisellä PCM-äänellä taajuudella 24 kHz