Snabbstart: Integrera text-till-tal API:t med OpenAI SDK

Av Talflöde redaktion · Uppdaterad 2026-11-18

Denna sida visar hur du snabbt integrerar Talflödes text-till-tal-API i din e-learningplattform. Vi använder samma enkla struktur som OpenAI, så du kan använda deras officiella SDK med minimal anpassning. Du får en konkret steg-för-steg-guide för att generera ljudfiler från text, oavsett om du börjar från grunden eller bygger vidare på befintlig kod.

Guide är skriven för startups inom utbildning som behöver skala upp ljudproduktionen utan att anställa röster eller hantera komplex teknik. Vi täcker förberedelser, första anropet, validering av fält och felsökning av vanliga problem som rate limits eller språkval. Du lär dig hur du hanterar texter över 4096 tecken och väljer rätt format för dina kurser.

Snabbstart: Integrera text-till-tal API:t med OpenAI SDK

Vanliga frågor

Vad är base_url?

Base_url är adressen för API:et: https://api.playg123.com/v1. Genom att ändra base_url i OpenAI SDK:er kan du använda dem direkt mot Talflöde. Du behöver bara uppdatera adressen och använda din API-nyckel för autentisering vid varje begäran.

Hur ser en lyckad förfrågan ut?

En lyckad förfrågan returnerar ljudfilen direkt i response bodyt. Svarsformatet beror på hur du konfigurerar din klient, men strukturen följer standarden för speech-endpunkten. Svarsformatet beror på hur du konfigurerar din klient, men strukturen följer standarden för speech-endpunkten.

Vilka statuskoder finns?

Vi använder standard HTTP-statuskoder. 200 betyder att ljudet genererades framgångsrikt. 400-koder indikerar felaktig begäran, till exempel ogiltig modell eller röst. 429 används vid överskridna rate limits. 500-koder betyder ett internt serverfel. Se dokumentationen för fullständig lista över felkoder.

Hur hanterar jag rate limits?

Du har 60 förfrågningar per minut per nyckel (10 innan första påfyllning). Om du överskrider gränsen får du status 429. Vänta eller dela upp dina texter i mindre delar under 4096 tecken. Texter genereras ungefär i realtid (ca 25 tecken per sekund), så planera din bearbetning därefter.

Vad är en API-nyckel?

En API-nyckel är ditt autentiseringsmedel, startar med 'tts-'. Den skickas i headern som 'Authorization: Bearer <nyckel>'. Varje konto har en aktiv nyckel. Du kan generera en ny när som helst; den gamla inaktiveras omedelbart vid utgivning av den nya.

Kan jag använda python-klienten?

Ja, du kan använda officiella OpenAI SDK:er för Python. Ändra bara base_url till https://api.playg123.com/v1 och använd din Talflöde-nyckel. All funktionalitet för text-till-tal fungerar precis som med OpenAI, så du kan använda samma kodstruktur för att generera ljudfiler.

Hur ser jag vilka röster som finns?

Använd GET /v1/voices för att hämta en lista över tillgängliga röster, språk och format. Du har åtta röster att välja mellan: aria, nova, luna, sage, felix, milo, atlas och orion. Varje röst kan tala alla 23 stödda språk korrekt.

Vad är skillnaden mellan tts-1 och tts-1-hd?

Båda modellerna använder samma motor och har samma pris: 10 dollar per miljon tecken. tts-1-hd är en högre kvalitetsvariant. Valet påverkar inte kostnaden eller hastigheten, men ger en annan ljudkvalitet. Du väljer modell via fältet 'model' i begäran.

Stöds streaming?

Nej, streaming stöds inte. Du skickar in texten och får tillbaka hela ljudfilen i svaret. Det finns inga WebSocket-anslutningar eller delvis ljudströmning. Ljudet genereras och returneras som en komplett fil efter bearbetning av begäran.

Hur ser jag loggar?

Vi sparar metadata för begäranden: tidpunkt, antal tecken och status. Denna information används för fakturering och kan ses i din kontodashboard på /get-api-key/. Detaljerade loggar för varje begäran i realtid finns inte tillgängliga via ett separat gränssnitt eller API.

Vad är response_format?

Du kan välja formatet mp3, wav, opus, flac eller pcm via parametern 'response_format'. Valet påverkar filstorlek och kompatibilitet. MP3 är vanligt för webb, medan WAV och FLAC ger förlustfri ljudkvalitet. PCM är rådata. Alla format returneras som en ljudfil i response bodyt.

Hur fungerar hastighetsparametern?

Parametern 'speed' reglerar talhastigheten mellan 0.25 och 4.0. Standard är 1.0. Lägre värden gör talet långsammare, högre värden snabbare. Detta påverkar inte priset, bara längden på den genererade ljudfilen. Justera hastigheten för att passa din målgrupp eller språkhastighet.

Vad händer vid fel?

Om syntesen misslyckas returneras felmeddelandet i JSON-svaret. Du debiteras inte för misslyckade förfrågningar; kostnaden återbetalas fullt ut. Kontrollera att texten är under 4096 tecken och att nyckeln är giltig. Vid serverfel (500) kan du prova igen efter kort väntan.

Hur uppdaterar jag min nyckel?

Gå till sidan /get-api-key/ i din dashboard. Där kan du generera en ny API-nyckel. När du skapar en ny nyckel inaktiveras den gamla omedelbart. Se till att uppdatera din kod eller klient med den nya nyckeln för att fortsätta använda API:et.

Första förfrågan

curl

curl https://api.playg123.com/v1/audio/speech \
  -H "Authorization: Bearer $TTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"tts-1","voice":"aria","input":"Hello from the API.","response_format":"mp3"}' \
  --output hello.mp3

Python (openai)

from openai import OpenAI

client = OpenAI(base_url="https://api.playg123.com/v1", api_key="tts-...")

with client.audio.speech.with_streaming_response.create(
    model="tts-1", voice="nova", input="Hello from Python.", response_format="mp3"
) as response:
    response.stream_to_file("hello.mp3")

Node.js (openai)

import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({ baseURL: "https://api.playg123.com/v1", apiKey: process.env.TTS_API_KEY });
const res = await client.audio.speech.create({ model: "tts-1", voice: "milo", input: "Hello from Node.js." });
fs.writeFileSync("hello.mp3", Buffer.from(await res.arrayBuffer()));
voice
ariakvinna
novakvinna
lunakvinna
sagekvinna
felixman
miloman
atlasman
orionman
language
arالعربية
zh中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

Förberedelser

Ljudvågsillustration för: Förberedelser

För att komma igång med Talflödes API behöver du först skapa ett konto på playg123.com. Du loggar in antingen med Google eller via e-post och lösenord. Detta skapar en plattform för att hantera din API-nyckel och övervaka din förbrukning.

En gång inloggad kan du generera din enskilda API-nyckel som krävs för autentisering. Välj sedan mellan modellerna "tts-1" eller "tts-1-hd", som delar samma motor och prisstruktur för att konvertera ditt kursmaterial till ljud.

Skapa konto

Skapa konto

Gå till /get-api-key/ och registrera dig med Google eller e-post. Kontot är specifikt för denna webbplats och ger dig tillgång till översikt över din balans och förbrukning.

Hämta API-nyckel

Hämta API-nyckel

Din API-nyckel visas direkt i kontovyn. Den börjar med "tts-" och används i headern "Authorization: Bearer". Du kan alltid generera en ny nyckel vid behov.

  • En aktiv nyckel per konto.

Välj modell

Välj mellan "tts-1" eller "tts-1-hd". Båda använder samma motor och har samma pris per miljon tecken. Modellen påverkar inte priset, bara kvalitetsnivån.

Första anropet

Ljudvågsillustration för: Första anropet

För att generera ljudfiler skickar du en POST-begäran till slutpunkten /v1/audio/speech. Du anger texten som ska läsas upp, väljer en röst och specificerar önskat ljudformat. API:t returnerar den färdiga ljudfilen direkt i svaret.

curl-exempel

Ett enkelt sätt att testa API:t är via curl. Byt ut YOUR_API_KEY mot din egen nyckel och anpassa texten efter behov. Svaret sparas i filen output.mp3.

  • curl -X POST "https://api.playg123.com/v1/audio/speech" \\ -H "Authorization: Bearer YOUR_API_KEY" \\ -H "Content-Type: application/json" \\ -d '{"model": "tts-1", "input": "Hej, detta är ett test", "voice": "nova", "response_format": "mp3"}' \\ -o output.mp3

JSON-struktur

Begäran skickas som JSON med fälten model, input, voice och response_format. Du kan även ange valfri hastighet mellan 0.25 och 4.0 samt ett språk (ISO-kod) för att styra uttal exakt.

Svar från servern

Vid lyckad syntes returneras ljudfilen direkt i response bodyt. Om något går fel får du en JSON-felmeddelande med statuskod och beskrivning av felet. Allt som inte är ljudfilen är JSON.

OpenAI SDK

Ljudvågsillustration för: OpenAI SDK

Att använda Talflödes API med OpenAI SDK är enkelt eftersom gränssnittet är kompatibelt. Du behöver bara ändra base_url till https://api.playg123.com/v1 och använda din API-nyckel. Koden returnerar ljudfilen direkt, vilket gör att du kan spara den eller skicka vidare till användaren.

Ändra base_url

Initiera OpenAI-klienten med din nyckel och pek base_url mot https://api.playg123.com/v1. Detta gör att befintlig kod fungerar utan större justeringar.

Använd samma kod

Använd samma metoder som vanligt. Skicka text, välj röst och format. API:t hanterar omvandlingen till ljud enligt specifikationen.

Exempelkod

Koden nedan visar hur du konfigurerar klienten och gör ett första anrop. Kom ihåg att hantera fel och rate limits (60 req/min).

  • Installera openai-paketet
  • Sätt OPENAI_API_KEY
  • Ändra base_url

Validering

Ljudvågsillustration för: Validering

När du skickar ett anrop till Talflödes API måste de tre grundläggande fälten vara ifyllda för att syntesen ska starta. Utan dessa parametrer returnerar servern ett felmeddelande och debiterar dig inte för försöket. Se till att din kod hanterar dessa krav innan du gör själva API-anropet.

Obligatoriska fält

Du måste alltid ange model, input och voice. Modellen kan vara "tts-1" eller "tts-1-hd". Texten i input får max 4096 tecken, och rösten måste matcha en av de tillgängliga presetarna. Alla fält är krav för att API:et ska kunna generera ljudfilen.

  • model: "tts-1" eller "tts-1-hd"
  • input: din text (max 4096 tecken)
  • voice: ett av de 8 tillgängliga namnen

Giltiga röster

Välj bland åtta profiler som aria, nova, luna, sage, felix, milo, atlas eller orion. Varje röst stödjer alla 23 språk som listats i dokumentationen. Du kan inte skapa egna röster eller klona befintliga; du använder enbart de fasta presetarna som finns tillgängliga via /v1/voices-endpointen.

Hastighetsintervall

Parametern speed accepterar värden mellan 0.25 och 4.0. Standardvärdet är 1.0. Du kan justera hastigheten för att passa ditt e-learning-material, men värden utanför intervallet ger ett valideringsfel. Justeringar påverkar inte teckenräkningen eller priset.

Felsökning

Ljudvågsillustration för: Felsökning

När du integrerar API:t kan du stöta på vanliga fel som förhindrar ljudgenerering. Genom att förstå felkoderna och rate limits sparar du tid i din utvecklingsprocess och säkerställer att dina e-learning-kurser laddas utan onödig fördröjning.

Denna guide hjälper dig att snabbt identifiera problem med nyckeln, förfrågningsbegränsningar och formatfel så att du kan återgå till att producera audio utan avbrott.

Vanliga felkoder

Du får ett 4xx-fel om parametrarna är felaktiga. Kontrollera att model är tts-1 eller tts-1-hd, att rösten finns i listan på /v1/voices och att texten inte överskrider 4096 tecken.

Ett 5xx-fel indikerar ett tillfälligt serverfel. Vänta några sekunder och försök igen; under belastning kan begäranden köa något längre än vanligt.

  • 400: Ogiltig begäran (felaktig modell eller röst)
  • 401: Felaktig eller saknad API-nyckel
  • 429: För många begäranden (se Rate limits)

Rate limits

Du har tillåtelse till 60 anrop per minut per nyckel. Innan din första top-up gäller en begränsning på 10 anrop per minut.

Om du överskrider gränsen får du HTTP 429. Vänta tills sluten av minutpasset eller topupa din balans för att återgå till full hastighet.

Kontrollera nyckel

Varje konto har en aktiv nyckel. Om du genererar en ny nyckel blir den gamla ogiltig omedelbart.

Felsök 401-fel genom att verifiera att du använder rätt nyckel från dashboarden och att prefixet är tts-.

Felsökning

Format

Ljudvågsillustration för: Format

Välj formatet som passar din e-learning-plattforms behov. MP3 är standard för webb och mobiler tack vare sin lilla filstorlek och breda kompatibilitet. WAV och FLAC erbjuder hög ljudkvalitet utan förlust, vilket är idealiskt för arkivering eller professionell redigering av kursmaterial. (Obs: FLAC nämns i fakta, WAV är okompreserat. 'utan förlust' är korrekt för FLAC, men WAV är PCM så det är också förlustfritt. Men 'utan förlust' är oftast kopplat till FLAC. Låt oss behålla det som det är om det inte är felaktigt. WAV är PCM, så det är förlustfritt. FLAC är lossless. Så det är korrekt. Men vänta, FAQ 11 säger 'obefintlig förlust' vilket är fel svenska för 'lossless'. Jag fixar FAQ 11.)

MP3

MP3 är det rekommenderade formatet för de flesta användningsfall. Det ger en bra balans mellan ljudkvalitet och filstorlek, vilket säkerställer snabb laddningstid för dina elever.

  • Stöds av alla moderna webbläsare och mobilappar.
  • Lågt bandbreidskrav för bättre upplevelse på mobila nätverk.

WAV

WAV är ett opaketerat format som bevarar originalkvaliteten från syntesen. Det är perfekt om du behöver bearbeta ljudfilerna ytterligare i en redigeringsprogramvara.

  • Ingen datakompression, maximal fidelitet.
  • Enkel att integrera i professionella ljudflöden.

FLAC

FLAC (Free Lossless Audio Codec) komprimerar ljudet utan kvalitetsförlust. Det ger mindre filer än WAV men behåller all information för perfekt återskapande.

  • Idealiskt för långtidslagring av kursmaterial.
  • Stödjs av de flesta avancerade ljudspelare.

Språk

Ljudvågsillustration för: Språk

API:t stödjer 23 språk som kan användas med vilken röst som helst. Du specificerar språket via ISO-kod för att säkerställa korrekt uttal och intonation.

Om du inte anger språk försöker API:t gissa det baserat på textens skrift. Latinsk text tolkas som engelska som standard, vilket kan ge fel resultat för andra språk.

För att undvika felaktig tolkning är det bäst att explicit ange språkkoden i varje begäran, särskilt när texten inte är engelsk.

ISO-koder

Använd standardiserade ISO 639-1-koder för att specificera språket. Du kan välja mellan arabiska, kinesiska, danska, engelska, franska, tyska, spanska och 18 andra språk som stöds av plattformen.

Exempel på koder: 'en' för engelska, 'sv' för svenska, 'de' för tyska och 'fr' för franska. Dessa koder skickas som ett fält i JSON-bodyn.

  • en: English
  • sv: Swedish
  • de: German
  • fr: French
  • es: Spanish
  • zh: Chinese

Automatisk detektering

API:t analyserar texten för att gissa språket om inget anges. Detta fungerar bra för engelska men är mindre pålitligt för andra språk med latinska tecken.

Om du skickar text på svenska utan att specificera språk, tolkas den som engelska. Detta leder till onaturligt uttal och felaktig rytm i den syntetiserade talen.

Tvinga språk

För att säkerställa korrekt språk, ange alltid 'language'-fältet i din begäran. Detta är särskilt viktigt för blandade språk eller när texten innehåller namn som kan missförstås.

Genom att tvinga fram språket undviker du att API:t gissar fel. Detta ger konsekvent ljudkvalitet oavsett vilken röst du väljer för din e-learning-kurs.

Längd & Delning

Ljudvågsillustration för: Längd & Delning

API:et har en strikt gräns på 4096 tecken per enskilt anrop, vilket inkluderar mellanslag och interpunktion. För korthistorier eller enkla instruktioner räcker detta oftast, men för längre kurstexter måste du hantera indelningen själv.

4096 tecken gräns

Varje begäran till /v1/audio/speech får inte överstiga 4096 tecken i input-fältet. Om din text är längre måste du dela upp den i mindre bitar innan du skickar dem till API:et.

Hantera långa texter

Dela in din kursmaterial i logiska stycken eller meningar som ligger under gränsen. Du kan skicka dessa sekventiellt. Eftersom förfrågningar bearbetas i kö kan det ta lite tid vid högre belastning, så planera in lite marginal för längre generationer.

Sammanfogning

När du har mottagit ljudfilerna för varje del, använd ett enkelt script eller bibliotek för att slå ihop dem till en enda fil. Detta ger en slät ljudupplevelse utan pauser mellan kapitlen i din e-learning-kurs.

Lyssna på de 8 rösterna

Varje exempel nedan genererades av detta API från samma mening. För korrekt uttal av annan latinbaserad text bör du alltid ange ISO-koden i förfrågan.

Avatar för rösten aria
ariakvinna
Avatar för rösten nova
novakvinna
Avatar för rösten luna
lunakvinna
Avatar för rösten sage
sagekvinna
Avatar för rösten milo
miloman

23 språk

Varje röst kan tala vilket som helst av dessa språk.

Källor och vidare läsning

  1. Wikipedia
  2. IETF RFC 7845: Ogg Opus
  3. Node.js documentation
  4. LibriVox public-domain audiobooks
  5. ISO 639 language codes
  6. LibriTTS-R paper (arXiv 2305.18802)
  7. Python documentation
  8. openai-node on GitHub
  9. FFmpeg documentation
  10. W3C WAI: making audio and video accessible
  11. TRON developer hub: TRC-20
  12. MDN: Web Speech API

Mer på denna webbplats