Обзор 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, до 20 000 символов |
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 активных ключей, переименовывать их в любое время и видеть, когда каждый из них использовался последний раз. Отзыв ключа сразу останавливает его запросы.
Аутентификация запроса
Отправьте ключ в качестве токена авторизации:
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, рассчитает любой уже произведенный аудио и освободит ключ, чтобы повторный запрос мог сгенерировать заново. Потоковые аудио-конечные точки отклоняют заголовок.
Кредиты
Синтез речи тратит кредиты из того же кошелька, что и приложение: 0.5 кредита (1 цент кошелька) за каждые начатые 30 секунд сгенерированного аудио. Каждый запрос содержит оценку (плюс небольшой запас) до начала генерации, затем рассчитывается по фактически произведенному аудио. Неиспользованный резерв возвращается; каждый рассчитанный запрос отображается в Настройки → Использование кредитов как API-синтез речи. Поле billed_credits в ответах API — это центы кошелька (2 цента = 1 отображаемый кредит). Если поток прерывается посередине, предложения, которые уже были доставлены, все равно списываются.
Если ваш баланс не покрывает резерв, API ответит 402 с кодом payment_required до генерации чего-либо.
Создание документов не тратит кредиты, но учитывается в ежедневном лимите документов вашего плана (Бесплатный: 3 в день; Unlimited: нет ежедневного лимита) и ограничениях по времени загрузки. Экспорт файлов не тратит кредиты.
Биллинг против воспроизведения в облаке в приложении
В приложении воспроизведение в облаке повторно использует кэш предложений на уровне документа: воспроизведение предложения, которое уже было сгенерировано на сервере, может стоить 0 отображаемых кредитов. Конечные точки речи REST и MCP всегда синтезируют свежий аудио и списывают за каждые начатые 30 секунд по той же ставке, когда происходит генерация. В API и MCP нет кэша воспроизведения.
Ограничения
| Ограничение | Значение |
|---|---|
Запросы к /documents | 120 в минуту на аккаунт |
Запросы к /audio/* | 60 в минуту на аккаунт |
| Параллельные запросы на синтез речи | 3 на аккаунт |
POST /audio/speech input | 5000 символов |
POST /audio/stream input | 20 000 символов |
| Текст документа | 500 000 символов |
| Активные 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} сохраняет заголовки временных меток транскрипта. Скрытие их — это только переключатель настроек читателя приложения.