API áttekintés
Hívja meg a Speechdash alkalmazását saját alkalmazásából, és hozza létre az API kulcsokat, amelyek engedélyezik ezt.
A Speechdash API lehetővé teszi, hogy saját alkalmazásod dokumentumokat hozzon létre és hangot generáljon az alkalmazásban használt hangokkal. Mindent, amit az API-n keresztül létrehoz, megjelenít a könyvtárában. Befejezett hang- és videó feliratok, amelyek az alkalmazásban készültek, is könyvtár-dokumentumként jelennek meg (source értéke transcription, transcript_id-vel). Nincs /transcripts REST erőforrás: használja a dokumentum végpontokat. Az API nem indít feliratolási feladatokat.
Alap URL:
https://api.speechdash.com/v1Egészségellenőrző (nincs API kulcs): GET https://api.speechdash.com/health
A gépek által olvasható szerződés a következő helyen publikálva van: https://api.speechdash.com/v1/openapi.json, így generálhat egy klienst a nyelvéhez.
Végpontok
| Metódus | Útvonal | Cél |
|---|---|---|
GET | /health | Szolgáltatási egészség (nem /v1 alatt) |
GET | /v1/openapi.json | OpenAPI 3.1 dokumentum |
GET | /v1/me | Fiók, terv és pénztár |
GET | /v1/documents | Könyvtár-dokumentumok listázása, beleértve a befejezett feliratokat |
POST | /v1/documents | Szöveges dokumentum létrehozása (source=api) |
GET | /v1/documents/{document_id} | Dokumentum olvasása és szövege |
PUT | /v1/documents/{document_id} | Cím, szöveg, nyelv, is_archived, vagy visibility frissítése |
DELETE | /v1/documents/{document_id} | Dokumentum törlése |
POST | /v1/documents/{document_id}/translate | Új fordított verzió (azonos hitel, mint az MP3 export) |
GET | /v1/documents/{document_id}/export | pdf, docx, txt, csv, srt, vagy vtt letöltése |
POST | /v1/audio/speech | Szintetizálás legfeljebb 5000 karakterig (JSON + hang) |
POST | /v1/audio/stream | WAV stream, legfeljebb 20 000 karakter |
POST | /v1/audio/stream/with-timestamps | SSE a mondatok szerinti hanggal és jelölőkkel |
GET | /v1/voices | Hangkatalógus |
GET | /v1/voices/{voice_id} | Egy hang előállítás |
Interaktív OpenAPI oldalak: Fiók, Dokumentumok, Hang, Hangok.
MCP szerver (AI segítők számára)
Ha a Cursor, Claude Desktop, vagy más MCP klienset használ, hozzáadhatja az hivatalos Speechdash MCP szervert helyett, hogy ne hívja meg magán a HTTP-t. Ez ugyanazt a könyvtárat nyújtja (beleértve a befejezett feliratokat), fordítást, exportálást, hangokat, fiók mentést, és nem streamelt hangszintetizálást, mint eszközöket, amelyek az azonos API kulcsokkal és számlázással működnek, mint ez a útmutató. A streamelt hangszintetizálás a REST-en marad.
Lásd az MCP szervert a teljes eszközlista és beállítások (stdio vagy Streamable HTTP) részleteiért. Olvashatod még az Agents hub marketing oldalon, amely a gépek által olvasható dokumentumokat tartalmazza, amelyek az AI rendszereknek szántak. A végfelhasználók az API kulcsok és MCP oldalon kezdhetnek el ezen a Help Center oldalon.
API kulcs létrehozása
Nyissa meg a Beállítások → API.
Kattints Új kulcsra és adj neki egy nevet, amely azt mutatja, hol lesz használva, például Produkció szerver.
Másold le a kulcsot azonnal. Csak a prefixe tárolódik, így egyszer mutatódik meg és soha többé nem.
Egy kulcs a fiókodra hat. Tartsa a szerverén, soha a böngészőben, mobil alkalmazásban, vagy nyilvános repo-ban. Ha egy kulcs szivárog, törölje le Beállítások → API oldalon és hozza létre újat.
Tartani lehet legfeljebb 10 aktív kulcsot, bármikor átnevezhetők, és láthatja, mikor használták utoljára. Egy kulcs törlése azonnal megakasztja a kéréseket.
Hitelesítés egy kéréshez
Küldje a kulcsot egy bearer tokenként:
curl https://api.speechdash.com/v1/me \
-H "Authorization: Bearer sh_live_your_key"A nem hitelesített kulcsú kérések 401 hibaüzenettel válaszolnak unauthorized kóddal.
A GET /me visszaadja a fiók ID-jét, email-címet, tervet és pénztári egyenlegét (wallet_cents és display_credits), valamint metadatot az használt API kulcsról. Használja a kulcs hitelesítésének ellenőrzésére (például a Zapierben).
A POST /documents és POST /audio/speech fogad egy opcionális Idempotency-Key fejléct. Megismétlés egy azonos kulccsal és testtel 24 órán belül újra lejátszhatja az első sikeres válaszot, így egy hálózati zavar nem hoz létre egy második dokumentumot vagy kétszer számol fel hangot. Ha egy hang válasz túl nagy ahhoz, hogy tárolódjon, egy azonos kulccsal való újraküldés 409 válaszot ad, helyett, hogy újra generálja (az eredeti kérés már számlázva volt). Egy kliens lekapcsolódása az /audio/speech végponton 204 válaszot ad, lezárja az eddig generált hangot és felszabadítja a kulcsot, így egy újraküldés újra generálhatja. A streamelt hang végpontok elutasítják a fejléct.
Hitel
A hangszintetizálás hitelt veszt a fiók pénztárából, mint az alkalmazásban: 0.5 hitel (1 pénztár cent) minden 30 másodpercért, amely hangot generál. Minden kérés előre becslést tartalmaz (kicsit többet, mint a szükséges), mielőtt a generálás elkezdődik, majd a ténylegesen generált hangra állítja be magát. Használatlan előrehozott hitel visszajut; minden lezárt kérés megjelenik a Beállítások → Hitel felhasználás oldalon API hangszintetizálás néven. A válaszban található billed_credits mező pénztár centben van (2 cent = 1 mutató hitel). Ha egy stream félbeszakad, a már elküldött mondatok még mindig számlázásra kerülnek.
Ha a pénztára nem fedheti a előrehozott hitelt, az API 402 válaszot ad payment_required kóddal, mielőtt generálna valamit.
A dokumentumok létrehozása nem veszt hitelt, de számít a terv napi dokumentum korláta (Free: 3 naponta; Unlimited: nincs napi korláta) és feltöltési időkorlátokra. A fájl exportálása nem veszt hitelt.
Számlázás vs alkalmazásban lévő Cloud lejátszás
Az alkalmazásban lévő Cloud lejátszás újrahasznosítja a dokumentumonkénti mondat kachelt: egy mondat lejátszása, amely már generálva volt a szerveren, 0 mutató hitelt lehet, hogy költsön. REST és MCP hang végpontok mindig friss hangot szintetizálnak és számlázzák a generálás kezdetétől 30 másodpercért, ugyanazt a ráta használva, mint amikor a generálás történik. Nincs lejátszási cache az API vagy MCP szintetizálásnál.
Korlátok
| Korlátok | Érték |
|---|---|
Kérések a /documents végpontra | 120 perc alatt, fiók szinten |
Kérések a /audio/* végpontra | 60 perc alatt, fiók szinten |
| Parallel hangkérések | 3 fiók szinten |
POST /audio/speech input | 5000 karakter |
POST /audio/stream input | 20000 karakter |
| Dokumentum szövege | 500000 karakter |
| Aktív API kulcsok | 10 |
A korlátok fiók szinten számolódnak, nem kulcs szinten, így extra kulcsok nem emelik a kvótád. Minden válasz tartalmazza az X-Request-ID, és a /documents valamint /audio/* is visszaadja az X-RateLimit-Limit, X-RateLimit-Remaining, és X-RateLimit-Reset fejléceket. Ideiglenesen idézd fel az X-Request-ID-t, ha a támogatáshoz fordulsz.
A hangkérések is parallelizmus korláttal rendelkeznek: egy negyedik párhuzamos kérés 429 válaszot kap, míg három még fut, így egy integráció nem tud monopolizálni a szintetizálást. Újraküldd a 429 és 503 hibaüzeneteket a Retry-After fejléce után.
Tartalmakat, amelyek hosszabbak a hangkorlátoknál, hozhat létre egy dokumentumot a POST /v1/documents végponttal és exportálja a hangját az alkalmazásból.
Dokumentumok: megosztás, fordítás, exportálás
Szerializált dokumentumok tartalmazzák a visibility-t és share_url-t (nulla, ha magánéletű). A PUT /v1/documents/{id} fogadja a visibility-t, hogy publikáljon egy olvasható, olvasható oldalat /share/document/{id}-n, és is_archived archiváláshoz vagy visszaállításhoz. Megosztott oldalak szövegesen csak olvashatóak. Nem lejátszanak számlázott hangot.
A POST /v1/documents/{id}/translate létrehoz egy új fordított verziót. Számlázza ugyanazt a hitel pénztárat, mint az MP3 exportálás (0.5 hitel minden 30 másodpercért, amely hangot becslés alapján generál), és 402 válaszot ad, ha a pénztár nem elegendő. 503 válaszot ad, ha a fordítás nem konfigurálva vagy leállt.
A GET /v1/documents/{id}/export?format=pdf|docx|txt|csv|srt|vtt letölti az aktuális verziót egy mellékletként. Adja hozzá a timestamps=1-et a PDF, DOCX, TXT és CSV részidőket tartalmazó beillesztéséhez. Az SRT és VTT a feliratra vagy teljes mondat időzítésre van szükség. A tárolt text a GET /v1/documents/{id}-n tartja a felirat időzítési fejléceket. Elrejtése csak egy olvasó beállítása.