Επισκόπηση API

Το API του Speechdash επιτρέπει στην δική σας εφαρμογή να δημιουργεί έγγραφα και να παράγει ομιλία με τους ίδιους φωνητικούς τύπους όπως και η εφαρμογή. Όλα όσα δημιουργείτε μέσω του API εμφανίζονται επίσης στη βιβλιοθήκη σας. Τελειωμένα αρχεία ακοής και μεταγραφές βίντεο που δημιουργούνται στην εφαρμογή εμφανίζονται επίσης ως έγγραφα της βιβλιοθήκης (source είναι transcription, με transcript_id). Δεν υπάρχει REST πόρος /transcripts: χρησιμοποιήστε τα endpoints των εγγράφων. Το API δεν ξεκινά εργασίες μεταγραφής.

Βάση URL:

https://api.speechdash.com/v1

Ελέγχος υγείας (χωρίς κλειδί API): GET https://api.speechdash.com/health

Το μηχανοαποδεκτό συμβόλαιο δημοσιεύεται στο https://api.speechdash.com/v1/openapi.json, έτσι μπορείτε να δημιουργήσετε έναν πελάτη για την γλώσσα σας.

Endpoints

Σελίδες OpenAPI αλληλεπίδρασης: Λογαριασμός, Έγγραφα, Ήχος, Φωνές.

Server MCP (για βοηθούς AI)

Αν χρησιμοποιείτε Cursor, Claude Desktop ή άλλο MCP πελάτη, μπορείτε να προσθέσετε το επίσημο server MCP του Speechdash αντί να κάνετε HTTP καλέσματα. Εξωτερικεύει την ίδια βιβλιοθήκη (συμπεριλαμβανομένων των τελειωμένων μεταγραφών), μετάφραση, εξαγωγή, φωνές, στιγμιότυπο λογαριασμού και μη ροή σύνθεσης ομιλίας ως εργαλεία που υποστηρίζονται από τα ίδια κλειδιά API και λογιστική όπως αυτό το οδηγό. Η ροή ομιλίας παραμένει σε REST.

Δείτε MCP server για την πλήρη λίστα εργαλείων και την ρύθμιση (stdio ή Streamable HTTP). Μπορείτε επίσης να διαβάσετε τον Agents hub στην ιστοσελίδα μάρκετινγκ για μηχανοαποδεκτές οδηγίες που αποσκοπούν σε συστήματα AI. Οι τελικοί χρήστες μπορούν να ξεκινήσουν από Κλειδιά API και MCP σε αυτόν τον Κέντρο Βοήθειας.

Δημιουργία κλειδιού API

Μπορείτε να διατηρήσετε έως και 10 ενεργά κλειδιά, να τα ανανεώσετε όποτε θέλετε και να δείτε πότε χρησιμοποιήθηκε τελευταία το καθένα. Η ακύρωση ενός κλειδιού σταματά τις αιτήσεις του αμέσως.

Αυθεντικοποίηση μιας αιτήσεως

Στέλνετε το κλειδί ως τοκέν bearer:

curl https://api.speechdash.com/v1/me \
 -H "Authorization: Bearer sh_live_your_key"

Οι αιτήσεις χωρίς έγκυρο κλειδί απαντούν με 401 και τον κώδικα unauthorized.

GET /me επιστρέφει τον κωδικό λογαριασμού σας, το email, το σχέδιο και την ισοδύναμη αξία του πορτοφολιού (wallet_cents και display_credits), καθώς και μεταδεδομένα σχετικά με το κλειδί API που χρησιμοποιήθηκε. Χρησιμοποιήστε το για να επιβεβαιώσετε ένα κλειδί μετά τη ρύθμιση (για παράδειγμα στο Zapier).

POST /documents και POST /audio/speech αποδέχονται ένα προαιρετικό κεφαλίδιο Idempotency-Key. Η επανάληψη του ίδιου κλειδιού με το ίδιο σώμα αναπαίζει την πρώτη επιτυχημένη απάντηση για 24 ώρες, έτσι μια μικρή διακοπή δικτύου δεν δημιουργεί δεύτερο έγγραφο ή διπλή λογιστική για ομιλία. Αν μια απάντηση ομιλίας είναι πολύ μεγάλη για να αποθηκευτεί, μια επανάληψη με το ίδιο κλειδί απαντά 409 αντί να αναπαραγάγει (η αρχική αιτήση είχε ήδη λογιστεί). Μια διακοπή σύνδεσης στο /audio/speech απαντά 204, καταλήγει σε οποιονδήποτε ήχο που έχει ήδη παραχθεί και απελευθερώνει το κλειδί για να μπορεί μια επανάληψη να αναπαραγάγει. Τα endpoints ροής ήχου απορρίπτουν το κεφαλίδιο.

Πιστώσεις

Η σύνθεση ομιλίας καταναλώνει πιστώσεις από το ίδιο πορτοφόλι με την εφαρμογή: 0.5 πιστώσεις (1 πορτοφόλι κεντ) ανά ξεκινούμενα 30 δευτερόλεπτα παραγόμενου ήχου. Κάθε αιτήση κρατά μια εκτίμηση (προσθέτοντας ένα μικρό περιθώριο) πριν ξεκινήσει η παραγωγή, και στη συνέχεια καταλήγει στον ήχο που παράχθηκε πραγματικά. Οι μη χρησιμοποιημένες κρατήσεις επιστρέφονται, και κάθε καταληγμένη αιτήση εμφανίζεται στο Ρυθμίσεις → Χρήση πιστώσεων ως Σύνθεση ομιλίας API. Το πεδίο billed_credits στις απαντήσεις του API είναι σε κέντια πορτοφολιού (2 κέντια = 1 ορατή πιστώση). Αν μια ροή διακοπεί κατά τη διάρκεια, οι προτάσεις που έχουν ήδη παραδοθεί εξακολουθούν να λογίζονται.

Αν η ισοδύναμη αξία του πορτοφολιού σας δεν μπορεί να καλύψει την κρατήση, το API απαντά με 402 και τον κώδικα payment_required πριν παράγει κάτι.

Η δημιουργία εγγράφων δεν καταναλώνει πιστώσεις, αλλά μετράται προς την ημερήσια όρια εγγράφων του σχεδίου σας (Δωρεάν: 3 την ημέρα; Unlimited: χωρίς ημερήσιο όριο) και τα όρια διάρκειας upload. Η εξαγωγή αρχείων δεν καταναλώνει πιστώσεις.

Λογιστική vs αναπαραγωγή Cloud στην εφαρμογή

Η αναπαραγωγή Cloud στην εφαρμογή επανχρησιμοποιεί τον κACHE πρότασης ανά έγγραφο: η αναπαραγωγή μιας πρότασης που έχει ήδη παραχθεί στον server μπορεί να κοστίζει 0 ορατές πιστώσεις. Τα endpoints ομιλίας REST και MCP συνθέτουν πάντα νέο ήχο και λογίζονται ανά ξεκινούμενα 30 δευτερόλεπτα με τον ίδιο ρυθμό όταν συμβαίνει η σύνθεση. Δεν υπάρχει κACHE αναπαραγωγής στο API ή MCP σύνθεση.

Όρια

Τα όρια ρυθμού μετρώνται ανά λογαριασμό, όχι ανά κλειδί, έτσι τα επιπλέον κλειδιά δεν αυξάνουν το όριο σας. Κάθε απάντηση μεταφέρει X-Request-ID, και /documents καθώς και /audio/* επιστρέφουν επίσης X-RateLimit-Limit, X-RateLimit-Remaining, και X-RateLimit-Reset. Αναφέρετε το X-Request-ID όταν επικοινωνείτε με την υποστήριξη.

Οι αιτήσεις ομιλίας έχουν επίσης όριο παράλληλης εκτέλεσης: μια τέταρτη ταυτόχρονη αιτήση απαντά με 429 ενώ τρέχουν ακόμα τρεις, έτσι μία ενσωμάτωση δεν μπορεί να αποκλειστεί από τη σύνθεση. Επαναλάβετε 429 και 503 μετά το κεφαλίδιο Retry-After.

Για περιεχόμενο μεγαλύτερο από τα όρια ομιλίας, δημιουργήστε ένα έγγραφο με POST /v1/documents και εξαγάγετε τον ήχο του από την εφαρμογή.

Έγγραφα: μοιραστείτε, μεταφράστε, εξαγάγετε

Σειριακά έγγραφα περιλαμβάνουν visibility και share_url (null όταν είναι ιδιωτικά). PUT /v1/documents/{id} αποδέχεται visibility για να δημοσιεύσει μια μη καταχωρημένη μόνο για ανάγνωση σελίδα στο /share/document/{id}, και is_archived για να αρχειοθετήσει ή να αποκαταστήσει. Οι μοιραζόμενες σελίδες είναι μόνο κείμενο. Δεν αναπαραγάγουν λογισμένο ήχο.

POST /v1/documents/{id}/translate δημιουργεί μια νέα μεταφρασμένη έκδοση. Λογίζεται το ίδιο πορτοφόλι πιστώσεων όπως η εξαγωγή MP3 (0.5 πιστώσεις ανά ξεκινούμενα 30 δευτερόλεπτα εκτιμώμενης ομιλίας) και απαντά με 402 όταν το πορτοφόλι είναι χαμηλό. Απαντά με 503 όταν η μετάφραση δεν είναι ρυθμισμένη ή είναι εκτός λειτουργίας.

GET /v1/documents/{id}/export?format=pdf|docx|txt|csv|srt|vtt κατεβάζει την τρέχουσα έκδοση ως επισύναψη. Προσθέστε timestamps=1 για να συμπεριλάβετε χρόνους τμήματος σε PDF, DOCX, TXT, και CSV. SRT και VTT χρειάζονται μεταγραφή ή πλήρεις χρονικές στιγμές προτάσεων. Αποθηκευμένο text στο GET /v1/documents/{id} διατηρεί τα κεφαλίδια χρονικών στιγμών μεταγραφής. Το κρύψιμό τους είναι μόνο ένα ρυθμιζόμενο στοιχείο από τον αναγνώστη της εφαρμογής.

Σχετικά