Τεκμηρίωση API για ενσωματώσεις

GET /api/v1/voices — φίλτρα: q (αναζήτηση με όνομα/style), language (ru, en, de…), gender (male/female), limit (προεπιλογή 200, μέγιστο 500), offset. Πέρασε το πεδίο voice από την απάντηση στο POST /tts.

Άβαταρ & γλώσσες. Άβαταρ: 302 στην εικόνα ή σε μια SVG gradient — βάλ’ το απευθείας στο <img>. Γλώσσες: tier = main (ready) | beta | soon.

Όλα τα endpoints απαιτούν ένα API key: την κεφαλίδα X-API-Key: <key> ή Authorization: Bearer <key> (εκτός από GET /api/v1/voices, GET /api/v1/status, GET /api/v1/languages και GET /api/v1/voices/{voice}/avatar — open). Το κλειδί δημιουργείται στον λογαριασμό σου → στην ενότητα “API”; το API είναι διαθέσιμο από το Starter plan και πάνω (αλλιώς 403). Η σύνθεση χρεώνει χαρακτήρες στο πλάνο του κλειδιού — με μηδενικό υπόλοιπο επιστρέφει 402. Το rate limit είναι ανά πλάνο: Starter — 30 αιτήσεις/λεπτό, Pro — 120, Business — 300, Scale — 600 (fallback 60); αν το ξεπεράσεις → 429, η κεφαλίδα Retry-After.

Η απάντηση είναι ένα δυαδικό αρχείο ήχου: audio/wav ή audio/mpeg (αν format=mp3)· για τηλεφωνικό response_format, το αντίστοιχο container του κωδικοποιητή (δείτε X-Audio-Format).

Δέχεται voice, text, language, instruct, speed, gain_db, eq, effect, background, bg_level, saturation, seed και segments (έως 40 στοιχεία: text, instruct έως 200 χαρακτήρες, silence 0–3000 ms). Απάντηση: ακατέργαστο PCM — 24 kHz, 16-bit, μονοφωνικό, little-endian (application/octet-stream, chunked)· δεν υπάρχει WAV header, ορίστε εσείς το sample rate.

Περάστε το πεδίο voice από την απόκριση στο POST /tts. Η τιμή voice παρακάτω είναι ενδεικτικό παράδειγμα· το πραγματικό αναγνωριστικό προέρχεται από την απόκριση. Η δημιουργία δικής σας φωνής είναι διαθέσιμη σε επί πληρωμή πλάνο· ο αριθμός των δικών σας φωνών είναι απεριόριστος — η δημιουργία μίας κοστίζει 25.000 χαρακτήρες από το υπόλοιπό σας (η αποθήκευση και η χρήση της είναι δωρεάν).

Το GET /api/v1/voices επιστρέφει μόνο το δημόσιο κατάλογο. Για να δείτε ΤΙΣ ΔΙΚΕΣ ΣΑΣ φωνές — τόσο όσες δημιουργήθηκαν μέσω API όσο και όσες δημιουργήθηκαν στον λογαριασμό/στούντιό σας — κάντε αυθεντικοποίηση με το API key σας και καλέστε αυτό το endpoint. Επιστρέφει τα δικά σας κλώνους (kind="own") και φωνές που αγοράστηκαν στο Marketplace (kind="marketplace"). Περάστε το πεδίο voice (slug) στο POST /api/v1/tts.

Το gender είναι null για τις δικές σας φωνές (δεν αποθηκεύεται)· το sample_url μπορεί να είναι null αν δεν υπάρχει δείγμα. Όταν γίνεται σύνθεση με τη δική σας φωνή, η γλώσσα λαμβάνεται από τη φωνή και υπερισχύει της παραμέτρου language στο POST /tts.

Πλήρης ροή copy-paste — δημιουργία, λίστα, σύνθεση (αντικαταστήστε το παράδειγμα κλειδιού με το δικό σας από Account → API):

Οι χαρακτήρες χρεώνονται ανά πλάνο (≈1 λεπτό ήχου = 1000 χαρακτήρες)· ισχύει το μηνιαίο όριο του πλάνου σε λεπτά απομαγνητοφώνησης.

GET /api/v1/status (χωρίς κλειδί) — ετοιμότητα του κινητήρα για πραγματικό χρόνο. POST /api/v1/warmup (με κλειδί· δεν χρεώνει χαρακτήρες) προθερμαίνει τον κινητήρα πριν από μια σειρά κλήσεων.

Το πεδίο code στο σώμα σφάλματος (αναγνώσιμο από μηχανή): plan_required — χρειάζεται ανώτερο πλάνο· voice_limit — το όριο φωνών του πλάνου· plan_quota — το μηνιαίο όριο λεπτών μεταγραφής έχει εξαντληθεί· email_unverified — επαληθεύστε το email σας· voice_conflict — το όνομα της φωνής είναι ήδη σε χρήση (κατά τη δημιουργία φωνής).

Το σώμα του σφάλματος είναι JSON { "error": "description", "code": "machine-readable" }. Πιθανές τιμές code: auth_required, plan_required, rate_limited, concurrency_limit, no_credits, voice_create_credits, bad_request, empty_text, text_too_long, ref_text_too_long, name_too_long, voice_limit, voice_conflict, voice_access, plan_quota, no_audio, engine_busy, engine_unavailable, engine_error, billing_unavailable, temporarily_unavailable. Σε αποτυχία δεν χρεώνονται χαρακτήρες — εκτός αν ο πελάτης διακόψει ένα stream (ο ήχος που παραδόθηκε χρεώνεται αναλογικά).

Όλοι οι κωδικοί σφάλματος

Πλήρης λίστα μηχανικών κωδικών στο πεδίο code: auth_required (401) · plan_required (403, API από Starter) · text_too_long, bad_request, name_required, ref_text_required, ref_text_too_long, name_too_long, audio_b64_required, consent_required, voice_required (400) · voice_access · voice_not_found (404) · no_credits (402) · body_too_large, audio_too_large (413) · concurrency_limit (429, concurrency) · rate_limited (429, με Retry-After) · engine_bad_request (engine 4xx) · engine_error, engine_unavailable, engine_not_configured, temporarily_unavailable, mp3_failed, telephony_failed, transcribe_failed (5xx) · client_abort (499, ο πελάτης διέκοψε τη σύνδεση).

Λεπτομέρειες

Πρακτικές λεπτομέρειες που είναι εύκολο να σας ξεφύγουν: το σώμα του αιτήματος περιορίζεται σε 2 MB για τα /v1/tts και /v1/tts_stream (αλλιώς 413) και σε base64 30 MB για το /v1/transcribe · το speaker είναι συνώνυμο του voice · ο δείκτης παύσης ‖ (U+2016) που τοποθετείται στο κείμενο δίνει ακριβώς 400 ms σιωπής · το instruct περικόπτεται σιωπηλά σε 500 χαρακτήρες και το lead_silence_ms περιορίζεται σε 5000 · χωρίς seed χρησιμοποιείται η τιμή 4242, ώστε η έξοδος να είναι αναπαραγώγιμη από προεπιλογή (αλλάξτε μόνοι σας το seed αν θέλετε διαφοροποίηση) · χωρίς language θεωρείται τα Γερμανικά · το GET /v1/languages δέχεται ?locale · το όριο ρυθμού μετράται ξεχωριστά ανά endpoint· τα δικά του όρια: /voices/create 5/min, /warmup 20/min, /voices/mine 60/min, ανοιχτά GET endpoints 120/min ανά IP · το POST /v1/voices/clone είναι ψευδώνυμο του /voices/create.

Η παράμετρος effect — μία προεπιλογή ανά αίτημα. Τα δωρεάν είναι διαθέσιμα σε όλους· τα premium — σε επί πληρωμή πακέτα.