Огляд API
Викликайте Speechdash з власного застосунку та створюйте API-ключі, які його авторизують.
API Speechdash дозволяє вашому застосунку створювати документи та генерувати мову за допомогою тих самих голосів, що й у додатку. Все, що ви створюєте через API, також з'являється у вашій бібліотеці. Завершені аудіо- та відеотранскрипції, створені в додатку, з'являються як документи бібліотеки (source — це transcription, з transcript_id). Немає ресурсу REST /transcripts: використовуйте кінцеві точки документів. API не запускає завдання транскрибування.
Базова URL:
https://api.speechdash.com/v1Перевірка стану (без API-ключа): GET https://api.speechdash.com/health
Машинно-читабельний контракт опубліковано за адресою https://api.speechdash.com/v1/openapi.json, тому ви можете сгенерувати клієнта для вашої мови.
Кінцеві точки
| Метод | Шлях | Мета |
|---|---|---|
GET | /health | Стан сервісу (не під /v1) |
GET | /v1/openapi.json | Документ OpenAPI 3.1 |
GET | /v1/me | Обліковий запис, план та гаманець |
GET | /v1/documents | Список документів бібліотеки, включаючи завершені транскрипції |
POST | /v1/documents | Створення текстового документа (source=api) |
GET | /v1/documents/{document_id} | Читання документа та його тексту |
PUT | /v1/documents/{document_id} | Оновлення назви, тексту, мови, is_archived, або visibility |
DELETE | /v1/documents/{document_id} | Видалення документа |
POST | /v1/documents/{document_id}/translate | Нова перекладена версія (такі ж кредити, як і експорт MP3) |
GET | /v1/documents/{document_id}/export | Завантаження pdf, docx, txt, csv, srt, або vtt |
POST | /v1/audio/speech | Синтез до 5000 символів (JSON + аудіо) |
POST | /v1/audio/stream | Поток WAV, до 20000 символів |
POST | /v1/audio/stream/with-timestamps | SSE з аудіо за реченнями та позначками |
GET | /v1/voices | Каталог голосів |
GET | /v1/voices/{voice_id} | Один настрій голосу |
Інтерактивні сторінки OpenAPI: Обліковий запис, Документи, Аудіо, Голоси.
Сервер MCP (для штучних помічників)
Якщо ви використовуєте Cursor, Claude Desktop або інший клієнт MCP, ви можете додати офіційний сервер Speechdash MCP замість безпосереднього виклику HTTP. Він пропонує ту саму бібліотеку (включаючи завершені транскрипції), переклад, експорт, голоси, знімок облікового запису та непотоковий синтез мови як інструменти, які підтримуються тими самими API-ключами та розрахунками, як і в цьому посібнику. Потоковий синтез мови залишається на REST.
Дивіться сервер MCP для повного списку інструментів та налаштувань (stdio або Streamable HTTP). Ви також можете прочитати Agents hub на маркетинговій сторінці для машинно-читабельних документів, орієнтованих на системи штучного інтелекту. Кінцевим користувачам можна почати з API-ключів та MCP у цьому Центрі допомоги.
Створення API-ключа
Відкрийте Налаштування → API.
Натисніть Новий ключ і дайте йому назву, яка вказує, де він буде використовуватися, наприклад Виробничий сервер.
Скопіюйте ключ негайно. Зберігається лише його префікс, тому він показується лише один раз і ніколи більше.
Ключ діє на ваш обліковий запис. Зберігайте його на сервері, ніколи в браузері, мобільному додатку або публічному репозиторії. Якщо ключ витік, відкликайте його з Налаштувань → API та створіть новий.
Ви можете зберігати до 10 активних ключів, перейменовувати їх у будь-який час і бачити, коли кожен з них був останнім разом використаний. Відкликання ключа негайно зупиняє його запити.
Автентифікація запиту
Надійшліть ключ як токен Bearer:
curl https://api.speechdash.com/v1/me \
-H "Authorization: Bearer sh_live_your_key"Запити без дійсного ключа відповідають 401 з кодом unauthorized.
GET /me повертає ваш ідентифікатор облікового запису, електронну пошту, план та залишок гаманця (wallet_cents і display_credits), а також метадані про використаний API-ключ. Використовуйте це для перевірки ключа після налаштування (наприклад, у Zapier).
POST /documents і POST /audio/speech приймають необов'язковий заголовок Idempotency-Key. Повторне виконання того самого ключа з тим самим тілом відтворює першу успішну відповідь протягом 24 годин, тому мережевий спам не створює другий документ або не рахує мову двічі. Якщо відповідь на мову надто велика для зберігання, повторне виконання з тим самим ключем відповідає 409 замість перегенерування (початковий запит вже був оплачений). Якщо клієнт відключився на /audio/speech, відповідь 204 підтверджує будь-яке аудіо, яке вже було вироблено, і звільняє ключ, щоб повторне виконання могло перегенерувати. Потокові кінцеві точки аудіо відхиляють заголовок.
Кредити
Синтез мови витрачає кредити з того самого гаманця, що й у додатку: 0.5 кредити (1 цент гаманця) на кожні 30 секунд генерованого аудіо. Кожен запит містить оцінку (плюс невеликий запас) до початку генерації, а потім підтверджується на основі фактично виробленого аудіо. Невикористана оцінка повертається; кожен підтверджений запит з'являється у Налаштуваннях → Використання кредитів як API синтез мови. Поле billed_credits у відповідях API — це цент гаманця (2 центів = 1 відображальний кредит). Якщо поток перерваний на півшляху, речення, які вже були доставлені, все одно рахуються.
Якщо ваш баланс не може покрити оцінку, API відповідає 402 з кодом payment_required до того, як щось буде згенеровано.
Створення документів не витрачає кредитів, але враховується у щоденній ліміті документів вашого плану (Безкоштовний: 3 на день; Unlimited: немає щоденного ліміту) та обмеженнях тривалості завантаження. Експорт файлів не витрачає кредитів.
Розрахунок проти відтворення в хмарі в додатку
Відтворення в хмарі Cloud у додатку повторно використовує кеш речень за документом: відтворення речення, яке вже було згенеровано на сервері, може коштувати 0 відображальних кредитів. Кінцеві точки REST і MCP для мови завжди синтезують нове аудіо та рахують за кожні 30 секунд початку генерації з тією ж ставкою, коли відбувається генерація. Немає кешу відтворення на синтезі API або MCP.
Обмеження
| Обмеження | Значення |
|---|---|
Запити до /documents | 120 на хвилину, на обліковий запис |
Запити до /audio/* | 60 на хвилину, на обліковий запис |
| Паралельні запити на синтез мови | 3 на обліковий запис |
POST /audio/speech input | 5000 символів |
POST /audio/stream input | 20000 символів |
| Текст документа | 500000 символів |
| Активні API-ключі | 10 |
Обмеження на швидкість обчислюються за обліковим записом, а не за ключем, тому додаткові ключі не підвищують вашу квоту. Кожна відповідь містить 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} зберігають заголовки часових позначок транскрипції. Приховування їх є лише налаштуванням читання додатку.