Dokumentation: Så här kommer du igång med vårt Text-till-tal API

Av Ljudväv redaktion · Uppdaterad 2026-11-19

Denna guide hjälper dig att integrera Ljudvävs text-till-tal API i din e-handel. Vi visar exakt hur du skapar konto, hämtar din API-nyckel och skickar din första begäran för att generera ljudfiler. Innehållet är anpassat för produktteam som behöver automatisera ljudinstruktioner och produktbeskrivningar utan onödiga funktioner.

Här hittar du steg-för-steg-instruktioner för både curl och OpenAI SDK, plus detaljer om tillgängliga röster, format och begränsningar. Du lär dig hantera fel, optimera hastighet och förstå hur karaktägräknningen fungerar.

Dokumentation: Så här kommer du igång med vårt Text-till-tal API

Vanliga frågor

Hur ser en lyckad respons ut?

En lyckad begäran returnerar en HTTP 200-status med ljudfilen i response body. Du kan välja format som mp3, wav, opus, flac eller pcm. Texten skickas i JSON-bodyn med fältet input. Modellen måste vara tts-1 eller tts-1-hd. Autentisering sker via Bearer-token i header. Ljudfilen returneras direkt utan ytterligare metadata i bodyn för enkel integration.

Vad betyder felkod 401?

Felkod 401 indikerar att din API-nyckel är felaktig eller saknas. Kontrollera att Authorization-headern innehåller giltigt Bearer-token. Nyckeln börjar med prefixet tts-. Om nyckeln är korrekt kan den vara inaktiverad om en ny har genererats. Varje konto har bara en aktiv nyckel. Generera en ny nyckel på /get-api-key/ och uppdatera den i din kod.

Kan jag använda samma nyckel på flera enheter?

Ja, du kan använda samma API-nyckel på flera enheter eller servrar samtidigt. Nyckeln är kopplad till kontot, inte till en specifik IP eller enhet. Hastighetsbegränsningen på 60 begäranden per minut gäller per nyckel oavsett antal enheter. Dela nyckeln fritt inom ditt team. Observera att en ny nyckel inaktiverar den gamla omedelbart.

Stöds async-behandling av ljud?

Nej, API:t är synkront. Du skickar text och får ljudfilen direkt i samma svar. Det finns inga webhooks eller async-endpoints för att hämta ljudet senare. För långa texter måste du hantera delning och sammanslagning av filer i din egen kod. Begäranden bearbetas i tur och ordning, vilket kan skapa kö vid hög belastning.

Hur ändrar jag hastigheten på rösten?

Använd fältet speed i JSON-bodyn för att justera hastigheten. Tillåtet intervall är 0.25 till 4.0, där 1.0 är normal hastighet. Lägre värden gör rösten långsammare, högre värden snabbare. Parametern skickas tillsammans med model, input och voice. Hastighetsändringen påverkar både ljudkvalitet och tidsåtgång för syntesen. Standardvärdet är 1.0 om inget anges.

Vilken modell ska jag välja för lägre kostnad?

Båda modellerna, tts-1 och tts-1-hd, har samma pris och motor. Kostnaden är $10 per miljon tecken oavsett val. Välj tts-1 för standardkvalitet eller tts-1-hd för högre ljudkvalitet. Det finns ingen prisskillnad mellan dem. Båda stöder alla röster och språk. Välj baserat på dina krav på ljudkvalitet snarare än kostnad.

Finns det en rate limit per dag?

Nej, det finns ingen daglig gräns för antal begäranden. Hastighetsbegränsningen är 60 begäranden per minut per nyckel. Efter att du har gjort din första top-up ökar gränsen från 10 till 60 begäranden per minut. Det finns ingen övre gräns för total förbrukning under en dag. Begränsningen är designad för att skydda servrarna vid spetsbelastning.

Hur hanterar jag text över 4096 tecken?

API:t accepterar maximalt 4096 tecken per begäran. För längre texter måste du dela upp texten i mindre delar i din kod. Skicka varje del separat till API:t och sammanfog sedan de returnerade ljudfilerna till en enda fil. Detta görs på kundsidan. Varje del räknas separat mot din förbrukning. Se till att dela vid meningsgränser för bättre flyt.

Vilket format är bäst för mobil?

Opus är ett effektivt format med bra kompression, lämpligt för mobil. MP3 har brett stöd. WAV och FLAC ger högre kvalitet men större filstorlekar. PCM är obearbetat ljud. Alla format stöds av API:t. Välj baserat på dina specifika krav på filstorlek och kompatibilitet.

Kan jag skicka flera röster i samma request?

Nej, varje begäran kan bara innehålla en enda röst. Du måste skicka separata begäranden för varje röst som ska användas. Fältet voice accepterar en sträng med namnet på rösten, till exempel aria eller felix. Du kan växla röst mellan delar av texten genom att göra flera API-anrop. Varje begäran returnerar en separat ljudfil.

Hur ser endpoints för voices ut?

Använd GET /v1/voices för att hämta information om tillgängliga röster. Endpunkten returnerar en lista över röster, språk, format och pris. Du kan också använda GET /v1/models för modellinformation. Base URL är https://api.z63.info/v1. Svaret är i JSON-format. Använd denna endpoint för att dynamiskt ladda röstval i ditt gränssnitt.

Stöds custom pronunciation?

Nej, det stöds inte. Det finns inget stöd för SSML eller anpassade uttalslexikon. Du kan inte specificera hur specifika ord ska uttalas. Uttalet styrs helt av röstmotorn och språkinställningen. För specifika uttal kan du prova att stava om ord fonetiskt i input-texten. Detta är en begränsning i den nuvarande implementationen av API:t.

Vad är skillnaden på tts-1 och tts-1-hd?

Skillnaden ligger i ljudkvalitet, men inte i pris eller motor. tts-1-hd ger högre ljudkvalitet jämfört med tts-1. Båda kostar $10 per miljon tecken. Båda stöder samma röster och språk. Välj tts-1-hd om du prioriterar ljudkvalitet. tts-1 är tillräckligt för de flesta användningsområden. Det finns ingen prestandaskillnad i bearbetningstid mellan modellerna.

Hur loggar jag mina begäranden?

API:t sparar metadata för varje begäran, inklusive tid, teckenantal och status. Denna information används för fakturering och kan ses på /get-api-key/. Du kan logga dina egna begäranden i din kod genom att spara svarskoder och tidsstämplar. Felaktiga begäranden returneras utan kostnad. Använd GET /v1/voices eller /v1/models för att validera konfiguration innan produktion.

Första förfrågan

curl

curl https://api.z63.info/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.z63.info/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.z63.info/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

Skapa konto och hämta nyckel

Ljudvågsillustration för: Skapa konto och hämta nyckel

För att börja använda TTS API:t registrerar du ett konto på /get-api-key/ via Google eller e-post. Observera att kontona är bundna till denna specifika webbplats. Google-användare får en startkredit på 0,50 USD som gäller i sju dagar, medan e-postkonto skapas utan bonus.

Registrera dig via Google eller e-post

Registrera dig via Google eller e-post

Gå till sidan /get-api-key/ och välj inloggningsmetod. Google-inloggning aktiverar direkt en provkredit på 0,50 USD motsvarande cirka 50 000 tecken. E-postkonto kräver ingen kredit men ger full åtkomst till API:t omedelbart efter verifiering.

  • Ingen kreditkrav för e-postkonto
  • Google-konto ger 0,50 USD startkredit
  • Krediten löper ut efter 7 dagar

Hitta API-nyckeln i dashboarden

Hitta API-nyckeln i dashboarden

När du loggat in ser du din aktiva API-nyckel i dashboarden. Nyckeln identifieras med prefixet 'tts-'. Du ser även din återstående saldo och förbrukade tecken i realtid.

Utge ny nyckel om nödvändigt

Du kan generera en ny nyckel när som helst. Den gamla nyckeln slutar gälla omedelbart vid utgivning av den nya, vilket säkerställer att endast en nyckel är aktiv per konto.

Första begäran med curl

Ljudvågsillustration för: Första begäran med curl

Skicka en POST-begäran till https://api.z63.info/v1/audio/speech med ditt API-nyckel i Authorization-huvudet. Du mottar en ljudfil direkt i svarskroppen.

POST-endpunkten för speech

Använd curl för att skicka texten till API:et. Endpunkten accepterar JSON och returnerar ljudet direkt.

  • POST https://api.z63.info/v1/audio/speech
  • Header: Authorization: Bearer tts-...

JSON-body med input och voice

Body:t innehåller model, input-text och voice. Max 4096 tecken per begäran. Spaces och interpunktion räknas som tecken.

  • model: "tts-1" eller "tts-1-hd"
  • voice: t.ex. "nova" eller "felix"
  • input: din textsträng

Mottaga ljudfilen

Svaret innehåller ljuddata i valt format (mp3, wav, opus, flac, pcm). Filen returneras direkt i response-body:t utan extra lagring.

Använda OpenAI SDK

Ljudvågsillustration för: Använda OpenAI SDK

Ljudväv:s API följer samma strukturer som OpenAI:s speech-endpunkt. Genom att justera base_url till https://api.z63.info/v1 kan du använda befintliga klientbibliotek utan att ändra koden för varje anrop. Detta gör integrationen snabb och förutsägbar för befintliga system.

Ändra base_url till api.z63.info

I dina SDK-inställningar anger du den nya bas-URL:n. Detta dirigerar alla begäranden till Ljudvävs servrar istället för OpenAI. Endpunkten för att generera ljudfilen är v1/audio/speech.

Använd samma klasser som vanligt

Alla klasser och metoder för att hantera ljudfiler fungerar exakt som vanligt. Du behöver inte lära dig nya objekt eller anropsstrukturer. Parametrar som model, input, voice och response_format hanteras på samma sätt.

Konfigurera API-nyckeln

Din API-nyckel skickas i Authorization-headern. Se till att du använder rätt nyckel kopplad till ditt konto på z63.info. Nyckeln börjar med tts- och ger tillgång till 60 begäranden per minut.

Tillgängliga format

Ljudvågsillustration för: Tillgängliga format

Välj formatet utifrån din användningsmiljö för att balansera filstorlek och ljudkvalitet. API:et returnerar ljudfilen direkt i svaret, vilket gör det enkelt att integrera i din e-handelsflöde utan extra bearbetning.

Alla format stöds av de flesta moderna webbläsare. Du kan växla format utan att ändra din API-struktur, vilket underlättar vid testning av olika ljudkvaliteter för produktdescriptioner.

MP3 för webb

MP3 är det rekommenderade formatet för ljudspelare på produkt sidor och i e-postkampanjer. Det ger en bra balans mellan ljudkvalitet och filstorlek, vilket snabbar upp laddningstiden för besökare på mobila enheter.

WAV för hög kvalitet

Välj WAV när du behöver oförstörd ljudkvalitet för högtalare eller presentationer. Filerna blir större än MP3, men det undviker komprimeringsartefakter som kan påverka tydligheten vid tekniska instruktioner.

OPUS och FLAC för arkivering

OPUS erbjuder hög komprimering med låg filstorlek, lämpligt för lagring av stora ljudarkiv. FLAC ger förlustfri komprimering för långtidslagring där du vill behålla originalkvaliteten utan att uppta onödigt mycket diskutrymme.

Röster och parametrar

Ljudvågsillustration för: Röster och parametrar

API:t stödjer åtta röster med olika karaktäristika, från den varma narrativ rösten "aria" till den djupa dokumentärröstens "orion". Varje röst kan hantera alla 23 tillgängliga språk, oavsett om det gäller svenska, engelska eller arabiska. Val av röst sker genom att specificera fältet voice i din JSON-body.

Välj voice från 8 alternativ

Du kan välja mellan fyra kvinnliga röster (aria, nova, luna, sage) och fyra manliga röster (felix, milo, atlas, orion). Alla röster är baserade på licensierade inspelningar och bär en osynlig vattenstämpel för att markera dem som syntetiskt tal.

  • Aria: varm, klar berättarröst
  • Nova: ljus, energisk
  • Luna: mjuk, berättande
  • Sage: lugn, instruerande
  • Felix: energisk, reklam
  • Milo: trevlig, konverserande
  • Atlas: neutral, nyhetsliknande
  • Orion: djup, dokumentär

Ställ in hastighet 0.25–4.0

Hastighetsparametern speed accepterar värden mellan 0.25 och 4.0. Standardvärdet är 1.0. Justera hastigheten för att anpassa talet till din videos ljudspår eller för att spara kostnader genom att tala snabbare om kvalitet inte är primärt.

Ange språkkod vid behov

Om du inte anger language gissas språket utifrån teckensnittet; latinska tecken tolkas som engelska. För övriga språk med latinskt alfabet, som svenska eller tyska, bör du explicit ange ISO-koden för att säkerställa korrekt uttal och intonation.

Röster och parametrar

Felsökning och felmeddelanden

Ljudvågsillustration för: Felsökning och felmeddelanden

När API:et returnerar HTTP-status 429 har du överskridit gränsen på 60 begäranden per minut. Vänta några sekunder eller implementera en enkel backoff-strategi innan du försöker igen. Under de första minuterna, innan första top-up, är gränsen striktare: endast 10 begäranden per minut gäller.

Hantera 429 för rate limits

Kontrollera alltid responsens Retry-After-headern för att se exakt hur lång väntetid som krävs. Om du använder en hög volym bör du sprida ut dina anrop jämnt över minuten istället för att skicka dem i klumpar.

  • Standardgräns: 60 requests/minut per nyckel.
  • Gräns för nya konton: 10 requests/minut.
  • Vänta på Retry-After-värdet innan ny request.

Kontrollera giltig API-nyckel

En felaktig eller utgången nyckel returnerar status 401. Se till att headern Authorization: Bearer tts-... innehåller hela nyckelsträngen utan mellanslag. Du kan generera en ny nyckel i dashboarden när som helst; den gamla slutar gälla direkt.

  • Format: Bearer tts-<din_nyckel>.
  • Ny nyckel ersätter den gamla omedelbart.
  • Kontrollera att inget mellanslag finns efter 'Bearer'.

Validera JSON-struktur

Felaktig JSON-syntax ger ett 400-fel. Se till att input, model och voice är definierade. Texten får max 4096 tecken. Kontrollera att du inte inkluderar okända fält eller att strängvärdena är korrekt inbäddade i dubbla citattecken.

  • Obligatoriska fält: model, input, voice.
  • Max tecken per input: 4096.
  • Använd validerare för JSON innan du skickar requesten.

Begränsningar att känna till

Ljudvågsillustration för: Begränsningar att känna till

För att undvika fel är det viktigt att förstå API:ets grundläggande begränsningar. Dessa påverkar hur du strukturerar dina anrop och hanterar långa texter i dina e-handelsflöden.

Genom att anpassa din kod efter dessa gränser säkerställer du en stabil och förutsägbar leverans av ljudfiler utan onödig komplexitet.

Max 4096 tecken per request

Varje API-anrop kan innehålla högst 4096 tecken i input-fältet. Detta inkluderar mellanslag och interpunktion. För längre produktbeskrivningar eller instruktioner måste du dela upp texten i mindre bitar och sammanfoga de returnerade ljudfilerna.

Vi rekommenderar att du implementerar en logik som automatiskt delar upp texten vid meningsgränser för att undvika att en mening klippas mitt i.

  • Max längd: 4096 tecken per anrop
  • Tecken inkluderar mellanslag och skiljetecken
  • För längre texter: splittra och sammanfoga ljudfiler

60 requests per minut

Du har tillgång till 60 anrop per minut per API-nyckel. Innan din första top-up är gränsen 10 anrop per minut. Om du överskrider gränsen returneras ett 429-fel.

För e-handel med höga volymer kan det vara nödvändigt att implementera backoff-strategier eller använda flera nycklar om ni har tillgång till flera konton.

Längre texter som kräver flera anrop för att bearbetas kan snabbt fylla på din kvot, så planera era batch-job accordingly.

Ingen SSML-stöd

API:et stöder inte SSML (Speech Synthesis Markup Language). Det innebär att du inte kan styra uttal, pauser eller tonläge via XML-taggar i texten.

Du kan däremot justera hastigheten globalt via speed-parametern eller välja mellan åtta olika röster för att matcha tonläget i era innehåll.

För mer avancerad kontroll av uttal krävs att du manuellt justerar texten eller använder externa verktyg för att förbereda texten innan den skickas till API:et.

Exempel på kod

Ljudvågsillustration för: Exempel på kod

Här är tre konkreta exempel på hur du integrerar TTS API:t i din e-handel. Vi visar kod för Python, Node.js och en ren HTTP-begäran för att du snabbt ska kunna testa och implementera lösningen i era befintliga arbetsflöden.

Alla exempel använder standardparametrarna för modell, text och röst. Du kan enkelt anpassa hastighet eller format beroende på om ljudet ska spelas upp i realtid eller laddas ner som en fil.

Python med OpenAI-bibliotek

Installera OpenAI-biblioteket och använd base_url för att peka mot vår endpoint. Detta gör att du kan använda samma klasser som vanligt men med vår API-nyckel.

Koden nedan visar hur du skickar en begäran och sparar den genererade ljudfilen lokalt. Glöm inte att hantera felfall och rate limits enligt dokumentationen.

  • pip install openai
  • from openai import OpenAI
  • client = OpenAI(base_url='https://api.z63.info/v1', api_key='tts-...')

Node.js exempel

Använd fetch eller axios för att skicka en POST-begäran till speech-endpunkten. Se till att inkludera rätt headers och JSON-body med din text och röstval.

Svaret är en ljudfil som du kan skriva till disk eller direkt skicka vidare till kunden.

Raw HTTP-request

En enkel cURL-befäl är tillräckligt för att verifiera att din nyckel fungerar. Skicka en POST-begäran med JSON-body innehållande model, input och voice.

Svaret är en ljudfil i det valda formatet, till exempel MP3 eller WAV, som du kan spara eller bearbeta vidare.

Lyssna på de 8 rösterna

Varje exempel nedan genererades av detta API från samma mening. Detta är tillräckligt för de flesta e-handelsmiljöer utan att behöva optimera för extrem hög volym.

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. curl documentation
  3. LibriTTS-R paper (arXiv 2305.18802)
  4. Tether (USDT)
  5. FFmpeg documentation
  6. W3C WAI: making audio and video accessible
  7. LibriTTS-R corpus (OpenSLR 141)
  8. Node.js documentation
  9. Creative Commons Attribution 4.0
  10. ISO 639 language codes
  11. LibriVox public-domain audiobooks
  12. TRON developer hub: TRC-20

Mer på denna webbplats