Przegląd API
Wywołuj Speechdash z własnego aplikacji i tworzy klucze API, które ją autoryzują.
API Speechdash pozwala Twojej aplikacji tworzyć dokumenty i generować mowę za pomocą tych samych głosów, co w aplikacji. Wszystko, co utworzysz przez API, również pojawi się w Twojej biblioteczce. Skończone nagrania audio i transkrypcje wideo utworzone w aplikacji pojawiają się również jako dokumenty biblioteczki (source to transcription, z transcript_id). Nie ma zasobu REST /transcripts: używaj końcówek dokumentów. API nie uruchamia zadań transkrypcji.
Adres bazowy:
https://api.speechdash.com/v1Sprawdzenie stanu (bez klucza API): GET https://api.speechdash.com/health
Plik kontraktu maszynowo czytelny jest opublikowany pod adresem https://api.speechdash.com/v1/openapi.json, więc możesz wygenerować klienta dla swojego języka.
Końcówki
| Metoda | Ścieżka | Cel |
|---|---|---|
GET | /health | Sprawdzenie stanu usługi (nie pod /v1) |
GET | /v1/openapi.json | Dokument OpenAPI 3.1 |
GET | /v1/me | Konto, plan i portfel |
GET | /v1/documents | Lista dokumentów biblioteczki, w tym zakończonych transkrypcji |
POST | /v1/documents | Utwórz dokument tekstowy (source=api) |
GET | /v1/documents/{document_id} | Odczytaj dokument i jego tekst |
PUT | /v1/documents/{document_id} | Zaktualizuj tytuł, tekst, język, is_archived, lub visibility |
DELETE | /v1/documents/{document_id} | Usuń dokument |
POST | /v1/documents/{document_id}/translate | Nowa wersja przetłumaczona (takie same punkty za MP3 jak eksport) |
GET | /v1/documents/{document_id}/export | Pobierz pdf, docx, txt, csv, srt, lub vtt |
POST | /v1/audio/speech | Synthesaizuj do 5000 znaków (JSON + audio) |
POST | /v1/audio/stream | Strumieniowanie WAV, do 20 000 znaków |
POST | /v1/audio/stream/with-timestamps | SSE z audio na poziomie zdania i znakami |
GET | /v1/voices | Katalog głosów |
GET | /v1/voices/{voice_id} | Jedno ustawienie głosu |
Strony interaktywnego OpenAPI: Konto, Dokumenty, Audio, Głosy.
Serwer MCP (dla asystentów AI)
Jeśli używasz Cursor, Claude Desktop lub innego klienta MCP, możesz dodać oficjalny serwer MCP Speechdash zamiast samodzielnego wywoływania HTTP. Ekspozuje on tę samą biblioteczkę (włączając zakończone transkrypcje), tłumaczenie, eksport, głosy, zdjęcie konta oraz niestrumieniową syntezę mowy jako narzędzia obsługiwane przez te same klucze API i fakturę, jak w tym przewodniku. Strumieniowanie mowy pozostaje na REST.
Zobacz serwer MCP dla pełnej listy narzędzi i ustawień (stdio lub Streamable HTTP). Możesz również przeczytać Agents hub na stronie marketingowej, aby uzyskać maszynowo czytelne dokumenty skierowane do systemów AI. Użytkownicy końcowi mogą rozpocząć od kluczy API i MCP w tym Centrum Pomocy.
Tworzenie klucza API
Otwórz Ustawienia → API.
Kliknij Nowy klucz i nadaj mu nazwę opisującą miejsce jego użycia, na przykład Serwer produkcji.
Skopiuj klucz natychmiast. Przechowywane jest tylko jego prefiks, więc jest wyświetlany tylko raz i nigdy więcej.
Klucz działa na Twoim koncie. Przechowuj go na serwerze, nigdy w przeglądarce, aplikacji mobilnej ani publicznym repozytorium. Jeśli klucz wycieknie, odwołaj go z Ustawienia → API i utwórz nowy.
Możesz utrzymać do 10 aktywnych kluczy, zmieniać ich nazwy w dowolnym momencie i widzieć, kiedy każdy z nich był ostatnio używany. Odwołanie klucza natychmiast zatrzymuje jego żądania.
Autoryzacja żądania
Wyślij klucz jako token nośnika:
curl https://api.speechdash.com/v1/me \
-H "Authorization: Bearer sh_live_twój_klucz"Żądania bez ważnego klucza odpowiadają 401 z kodem unauthorized.
GET /me zwraca Twój identyfikator konta, adres e-mail, plan oraz saldo portfela (wallet_cents i display_credits), a także metadane dotyczące użytego klucza API. Użyj tego do weryfikacji klucza po ustawieniu (na przykład w Zapierze).
POST /documents i POST /audio/speech przyjmują opcjonalny nagłówek Idempotency-Key. Powtórzenie tego samego klucza z tym samym ciałem odtwarza pierwszą udaną odpowiedź przez 24 godziny, więc błyskotliwy problem sieciowy nie spowoduje utworzenia drugiego dokumentu ani dwukrotnego naliczenia mowy. Jeśli odpowiedź mowy jest zbyt duża, aby ją przechowywać, powtórzenie z tym samym kluczem odpowie 409 zamiast regenerować (pierwsze żądanie już zostało naliczone). Rozłączenie klienta na /audio/speech odpowie 204, rozliczy wszelkie już wyprodukowane audio i zwolni klucz, aby powtórzenie mogło odtworzyć. Końcówki strumieniowania audio odrzucają nagłówek.
Punkty
Synteza mowy zużywa punkty z tego samego portfela co aplikacja: 0.5 punktów (1 cent portfela) za każde rozpoczęte 30 sekund wygenerowanego audio. Każde żądanie trzyma szacunek (plus niewielki margines) przed rozpoczęciem generacji, a następnie rozlicza się do audio, które zostało faktycznie wyprodukowane. Niezrealizowany zapas jest zwracany; każde rozliczone żądanie pojawia się w Ustawienia → Użycie punktów jako API synteza mowy. Pole billed_credits w odpowiedziach API to ceny portfela (2 ceny = 1 wyświetlany punkt). Jeśli strumień zostanie przerwany w połowie, zdania już dostarczone nadal są naliczane.
Jeśli Twój bilans nie może pokryć zapasu, API odpowiada 402 z kodem payment_required przed wygenerowaniem czegoś.
Tworzenie dokumentów nie zużywa punktów, ale liczy się w dziennej limicie dokumentów Twojego planu (Darmowy: 3 dziennie; Unlimited: brak dziennej limity) oraz ograniczeniach czasu uploadu. Eksport plików nie zużywa punktów.
Fakturacja vs odtwarzanie w chmurze w aplikacji
Odtwarzanie w aplikacji Cloud ponownie używa bufora zdań na poziomie dokumentu: odtwarzanie zdania, które już zostało wygenerowane na serwerze, może kosztować 0 punktów wyświetlanych. Końcówki REST i MCP syntezy mowy zawsze generują świeże audio i naliczają za każde rozpoczęte 30 sekund w tym samym tempie, gdy generacja występuje. Nie ma bufora odtwarzania w API ani MCP syntezy.
Limity
| Limit | Wartość |
|---|---|
Żądania do /documents | 120 na minutę, na konto |
Żądania do /audio/* | 60 na minutę, na konto |
| Równoległe żądania mowy | 3 na konto |
POST /audio/speech input | 5000 znaków |
POST /audio/stream input | 20 000 znaków |
| Tekst dokumentu | 500 000 znaków |
| Aktywne klucze API | 10 |
Limity żądań są liczone na konto, a nie na klucz, więc dodatkowe klucze nie podnoszą Twojej kwoty. Każda odpowiedź zawiera X-Request-ID, a /documents oraz /audio/* również zwracają X-RateLimit-Limit, X-RateLimit-Remaining, i X-RateLimit-Reset. Cytuj X-Request-ID, gdy kontaktujesz się z obsługą.
Żądania mowy mają również ograniczenie równoległości: czwarte równoległe żądanie odpowiada 429, podczas gdy trzy są jeszcze w trakcie, więc jedna integracja nie może monopolizować syntezy. Powtarzaj 429 i 503 po nagłówku Retry-After.
Dla treści dłuższych niż limity mowy, utwórz dokument z POST /v1/documents i wyeksportuj jego audio z aplikacji.
Dokumenty: udostępnij, przetłumacz, eksportuj
Zserializowane dokumenty zawierają visibility i share_url (null, gdy prywatne). PUT /v1/documents/{id} przyjmuje visibility, aby opublikować nieulistowany, tylko do odczytu stronę pod /share/document/{id}, oraz is_archived, aby archiwizować lub przywracać. Udostępnione strony są tylko tekstowe. Nie odtwarzają naliczonego audio.
POST /v1/documents/{id}/translate tworzy nową przetłumaczoną wersję. Nalicza te same punkty portfela co eksport MP3 (0.5 punktów za rozpoczęte 30 sekund oszacowanej mowy) i odpowiada 402, gdy portfel jest niedostateczny. Odpowiada 503, gdy tłumaczenie nie jest skonfigurowane lub jest wyłączone.
GET /v1/documents/{id}/export?format=pdf|docx|txt|csv|srt|vtt pobiera bieżącą wersję jako załącznik. Dodaj timestamps=1, aby włączyć czasy sekcji w PDF, DOCX, TXT i CSV. SRT i VTT wymagają transkrypcji lub pełnych czasów zdań. Przechowywany text na GET /v1/documents/{id} zachowuje nagłówki czasów transkrypcji. Ukrywanie ich jest tylko przełącznikiem czytnika aplikacji.