API 개요
자신의 애플리케이션에서 Speechdash를 호출하고, 이를 권한 부여하는 API 키를 생성합니다.
Speechdash API는 자신의 애플리케이션에서 문서를 생성하고 앱과 같은 음성으로 음성 합성을 수행할 수 있게 해줍니다. API를 통해 생성한 모든 내용은 라이브러리에 표시됩니다. 앱에서 완료된 오디오 및 비디오 전사본은 라이브러리 문서로도 나타납니다 (source는 transcription이며, transcript_id가 포함됨). /transcripts REST 리소스는 없습니다. 문서 엔드포인트를 사용하세요. API는 전사 작업의 시작을 하지 않습니다.
베이스 URL:
https://api.speechdash.com/v1헬스 체크 (API 키 없음): GET https://api.speechdash.com/health
기계가 읽을 수 있는 계약은 https://api.speechdash.com/v1/openapi.json에서 발행되어 있습니다. 이를 통해 언어별 클라이언트를 생성할 수 있습니다.
엔드포인트
| Method | Path | Purpose |
|---|---|---|
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 | 최대 5,000 문자의 음성 합성 (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 서버 (AI 어시스턴트용)
Cursor, Claude Desktop 또는 다른 MCP 클라이언트를 사용한다면, 직접 HTTP를 호출하는 대신 공식 Speechdash MCP 서버를 추가할 수 있습니다. 이는 같은 라이브러리 (완료된 전사본 포함), 번역, 내보내기, 음성, 계정 스냅샷, 그리고 비스트리밍 음성 합성을 제공하며, 이 가이드에서 설명한 API 키와 청구 방식에 의해 지원됩니다. 스트리밍 음성 합성은 REST에 남아 있습니다.
MCP 서버에 대한 전체 도구 목록 및 설정은 MCP 서버에서 확인할 수 있습니다 (stdio 또는 Streamable HTTP). 또한, AI 시스템을 위한 기계가 읽을 수 있는 문서는 Agents hub에서 마케팅 사이트에서 읽을 수 있습니다. 최종 사용자는 이 도움말 센터의 API 키 및 MCP에서 시작할 수 있습니다.
API 키 생성
설정 → API를 엽니다.
새 키를 클릭하고, 어디에서 사용할지 나타내는 이름을 지정합니다. 예를 들어 Production 서버와 같이.
키를 즉시 복사합니다. 저장되는 것은 접두사만이며, 한 번만 표시되고 다시는 표시되지 않습니다.
키가 계정에 영향을 미칩니다. 서버에만 키를 보관하고, 브라우저, 모바일 앱, 또는 공용 저장소에 절대 저장하지 마세요. 키가 누출되면 설정 → API에서 폐기하고 새로운 키를 생성해야 합니다.
최대 10개의 활성 키를 보관할 수 있으며, 언제든지 이름을 변경하고 각 키가 마지막으로 사용된 시간을 볼 수 있습니다. 키를 폐기하면 그 키의 요청이 즉시 중단됩니다.
요청 인증
키를 베어러 토큰으로 보냅니다:
curl https://api.speechdash.com/v1/me \
-H "Authorization: Bearer sh_live_your_key"유효하지 않은 키로 요청하면 401 코드와 함께 unauthorized가 응답됩니다.
GET /me는 계정 ID, 이메일, 플랜, 지갑 잔액 (wallet_cents 및 display_credits), 그리고 사용된 API 키에 대한 메타데이터를 반환합니다. 이를 통해 설정 후 키를 확인할 수 있습니다 (예: Zapier에서).
POST /documents 및 POST /audio/speech은 선택적으로 Idempotency-Key 헤더를 허용합니다. 같은 키와 본문을 사용하여 재시도하면 24시간 동안 첫 번째 성공 응답이 재생성됩니다. 네트워크 문제로 인해 두 번째 문서가 생성되거나 음성 청구 두 번이 발생하지 않도록 합니다. 음성 응답이 저장할 수 없을 정도로 크면, 같은 키로 재시도하면 409 대신 재생성하지 않고 응답합니다 (원래 요청은 이미 청구되었습니다). /audio/speech에서 클라이언트 연결이 끊기면 204가 응답되며, 이미 생성된 오디오를 청구하고 키를 해제하여 재시도 시 재생성할 수 있습니다. 스트리밍 오디오 엔드포인트는 헤더를 거부합니다.
크레딧
음성 합성은 앱과 같은 지갑에서 크레딧을 사용합니다: 0.5 크레딧 (1 지갑 센트) 당 생성된 오디오의 시작된 30초당. 각 요청은 생성 시작 전에 추정치 (소량의 마진 포함)를 보유하고, 실제 생성된 오디오로 정산됩니다. 사용되지 않은 보유액은 환불됩니다. 각 정산된 요청은 설정 → 크레딧 사용에서 API 음성 합성으로 표시됩니다. API 응답의 billed_credits 필드는 지갑 센트입니다 (2센트 = 1 표시 크레딧). 스트림이 중간에서 중단되면 이미 전달된 문장들은 여전히 청구됩니다.
잔액이 보유액을 커버하지 못하면 API는 402 코드와 함께 payment_required로 응답하여 생성 전에는 아무것도 생성하지 않습니다.
문서 생성은 크레딧을 사용하지 않지만, 플랜의 일일 문서 제한 (무료: 3개/일; Unlimited: 일일 제한 없음)과 파일 업로드 시간 제한에 포함됩니다. 파일 내보내는 것은 크레딧을 사용하지 않습니다.
청구 vs 앱 내 클라우드 재생
앱 내 클라우드 재생은 문서별 문장 캐시를 재사용합니다: 이미 서버에서 생성된 문장을 재생하면 0 표시 크레딧이 소모될 수 있습니다. REST 및 MCP 음성 엔드포인트는 항상 신규 오디오를 생성하고 생성 시 시작된 30초당 같은 비율로 청구됩니다. API 또는 MCP 합성에는 재생 캐시가 없습니다.
제한
| 제한 | 값 |
|---|---|
/documents 요청 | 1분당 120개, 계정당 |
/audio/* 요청 | 1분당 60개, 계정당 |
| 병렬 음성 요청 | 3개, 계정당 |
POST /audio/speech input | 5,000 문자 |
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 내보내기와 같은 크레딧 지갑 (시작된 30초당 생성된 음성 0.5 크레딧)을 사용하고, 지갑이 부족하면 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}는 전사본 타이밍 헤더를 유지합니다. 이를 숨기는 것은 앱 리더의 토글 기능만입니다.