Tổng quan về API
Gọi Speechdash từ ứng dụng của bạn và tạo các khóa API để xác thực.
API của Speechdash cho phép ứng dụng của bạn tạo tài liệu và sinh lời nói với cùng các giọng nói như ứng dụng. Tất cả những gì bạn tạo thông qua API cũng sẽ xuất hiện trong thư viện của bạn. Các bản ghi âm và video đã hoàn thành được tạo trong ứng dụng sẽ xuất hiện như các tài liệu thư viện (source là transcription, với transcript_id). Không có tài nguyên REST /transcripts: sử dụng các điểm cuối tài liệu. API không khởi động các công việc ghi âm.
URL cơ sở:
https://api.speechdash.com/v1Kiểm tra trạng thái (không cần khóa API): GET https://api.speechdash.com/health
Hợp đồng có thể đọc máy được được công bố tại https://api.speechdash.com/v1/openapi.json, vì vậy bạn có thể tạo một client cho ngôn ngữ của mình.
Các điểm cuối
| Phương pháp | Đường dẫn | Mục đích |
|---|---|---|
GET | /health | Trạng thái dịch vụ (không nằm dưới /v1) |
GET | /v1/openapi.json | Tài liệu OpenAPI 3.1 |
GET | /v1/me | Tài khoản, gói dịch vụ và ví tiền |
GET | /v1/documents | Danh sách tài liệu thư viện, bao gồm bản ghi âm đã hoàn thành |
POST | /v1/documents | Tạo một tài liệu văn bản (source=api) |
GET | /v1/documents/{document_id} | Đọc một tài liệu và văn bản của nó |
PUT | /v1/documents/{document_id} | Cập nhật tiêu đề, văn bản, ngôn ngữ, is_archived, hoặc visibility |
DELETE | /v1/documents/{document_id} | Xóa một tài liệu |
POST | /v1/documents/{document_id}/translate | Tạo phiên bản dịch mới (sử dụng cùng số tín dụng như xuất MP3) |
GET | /v1/documents/{document_id}/export | Tải xuống pdf, docx, txt, csv, srt, hoặc vtt |
POST | /v1/audio/speech | Sinh lời nói lên đến 5.000 ký tự (JSON + âm thanh) |
POST | /v1/audio/stream | Phát trực tiếp WAV, lên đến 20.000 ký tự |
POST | /v1/audio/stream/with-timestamps | SSE với âm thanh theo câu và dấu hiệu |
GET | /v1/voices | Danh mục giọng nói |
GET | /v1/voices/{voice_id} | Một cài đặt giọng nói |
Trang OpenAPI tương tác: Tài khoản, Tài liệu, Âm thanh, Giọng nói.
Máy chủ MCP (cho trợ lý AI)
Nếu bạn sử dụng Cursor, Claude Desktop hoặc một khách hàng MCP khác, bạn có thể thêm máy chủ MCP chính thức của Speechdash thay vì gọi HTTP trực tiếp. Nó cung cấp cùng thư viện (bao gồm bản ghi âm đã hoàn thành), dịch, xuất, giọng nói, ảnh chụp tài khoản và tổng hợp giọng nói không phát trực tiếp như các công cụ được hỗ trợ bởi cùng các khóa API và tính toán như hướng dẫn này. Giọng nói phát trực tiếp vẫn ở REST.
Xem Máy chủ MCP để xem danh sách đầy đủ các công cụ và cài đặt (stdio hoặc Streamable HTTP). Bạn cũng có thể đọc Agents hub trên trang web marketing để tìm tài liệu có thể đọc máy nhằm mục đích hệ thống AI. Người dùng cuối có thể bắt đầu từ Khóa API và MCP trong Trung tâm trợ giúp này.
Tạo một khóa API
Mở Cài đặt → API.
Nhấp vào Tạo khóa mới và đặt tên cho nó để mô tả nơi nó sẽ được sử dụng, ví dụ như Máy chủ sản xuất.
Chép khóa ngay lập tức. Chỉ phần tiền tố được lưu trữ, vì vậy nó chỉ được hiển thị một lần và không bao giờ xuất hiện lại.
Một khóa tác động lên tài khoản của bạn. Hãy giữ nó trên máy chủ của bạn, không bao giờ trong trình duyệt, ứng dụng di động hoặc kho lưu trữ công khai. Nếu khóa rò rỉ, hãy hủy bỏ nó từ Cài đặt → API và tạo một khóa mới.
Bạn có thể giữ tối đa 10 khóa hoạt động, đổi tên chúng bất kỳ lúc nào và xem khi mỗi khóa được sử dụng lần cuối. Hủy bỏ một khóa sẽ ngừng các yêu cầu của nó ngay lập tức.
Xác thực một yêu cầu
Gửi khóa dưới dạng token mang theo:
curl https://api.speechdash.com/v1/me \
-H "Authorization: Bearer sh_live_your_key"Các yêu cầu không có khóa hợp lệ sẽ trả lời 401 với mã unauthorized.
GET /me trả về ID tài khoản, email, gói dịch vụ và số dư ví của bạn (wallet_cents và display_credits), cùng với thông tin bổ sung về khóa API được sử dụng. Sử dụng nó để xác minh một khóa sau khi thiết lập (ví dụ như trong Zapier).
POST /documents và POST /audio/speech chấp nhận một header tùy chọn Idempotency-Key. Lặp lại cùng một khóa với cùng nội dung sẽ tái phát lại phản hồi thành công đầu tiên trong vòng 24 giờ, vì vậy một lỗi mạng không tạo ra tài liệu hoặc tính toán giọng nói hai lần. Nếu phản hồi giọng nói quá lớn để lưu trữ, một yêu cầu lại với cùng một khóa trả lời 409 thay vì tái sinh (yêu cầu gốc đã được tính tiền). Một kết nối ngắt kết nối trên /audio/speech trả lời 204, thanh toán bất kỳ âm thanh nào đã được tạo và giải phóng khóa để một yêu cầu lại có thể tái sinh. Các điểm cuối âm thanh phát trực tiếp từ chối header này.
Tín dụng
Sinh lời nói tiêu tốn tín dụng từ cùng ví như ứng dụng: 0.5 tín dụng (1 xu ví) cho mỗi 30 giây lời nói được sinh ra. Mỗi yêu cầu giữ một ước tính (plus một phần nhỏ) trước khi sinh lời nói bắt đầu, sau đó thanh toán cho âm thanh thực sự được tạo ra. Tín dụng dư thừa không được sử dụng sẽ được hoàn lại; mỗi yêu cầu thanh toán sẽ xuất hiện trong Cài đặt → Sử dụng tín dụng như API sinh lời nói. Trường billed_credits trong phản hồi API là xu ví (2 xu = 1 tín dụng hiển thị). Nếu một luồng bị ngắt giữa chừng, các câu đã được giao vẫn được tính tiền.
Nếu số dư của bạn không đủ để đáp ứng yêu cầu giữ, API trả lời 402 với mã payment_required trước khi sinh bất kỳ thứ gì.
Tạo tài liệu không tiêu tốn tín dụng, nhưng nó được tính vào giới hạn tài liệu hàng ngày của gói dịch vụ của bạn (Miễn phí: 3 tài liệu/ngày; Unlimited: không có giới hạn hàng ngày) và giới hạn thời gian tải lên. Xuất tệp không tiêu tốn tín dụng.
Tính toán so với phát lại âm thanh Cloud trong ứng dụng
Phát lại Cloud trong ứng dụng tái sử dụng bộ nhớ đệm câu theo tài liệu: phát lại một câu đã được sinh trên máy chủ có thể chi phí 0 tín dụng hiển thị. Các điểm cuối REST và MCP sinh âm thanh mới và tính tiền theo từng 30 giây bắt đầu với cùng tỷ lệ khi sinh lời nói xảy ra. Không có bộ nhớ đệm phát lại trên tổng hợp giọng nói API hoặc MCP.
Giới hạn
| Giới hạn | Giá trị |
|---|---|
Yêu cầu đến /documents | 120 yêu cầu/phút, theo tài khoản |
Yêu cầu đến /audio/* | 60 yêu cầu/phút, theo tài khoản |
| Yêu cầu sinh lời nói song song | 3 yêu cầu/tài khoản |
POST /audio/speech input | 5.000 ký tự |
POST /audio/stream input | 20.000 ký tự |
| Văn bản tài liệu | 500.000 ký tự |
| Khóa API hoạt động | 10 |
Giới hạn yêu cầu được tính theo tài khoản, không theo khóa, vì vậy các khóa bổ sung không tăng giới hạn của bạn. Mỗi phản hồi mang X-Request-ID, và /documents cùng với /audio/* cũng trả về X-RateLimit-Limit, X-RateLimit-Remaining, và X-RateLimit-Reset. Trích dẫn X-Request-ID khi bạn liên hệ với hỗ trợ.
Các yêu cầu sinh lời nói cũng có giới hạn song song: một yêu cầu thứ tư đồng thời trả lời 429 trong khi ba yêu cầu vẫn đang chạy, vì vậy một tích hợp không thể độc quyền tổng hợp giọng nói. Lặp lại 429 và 503 sau header Retry-After.
Với nội dung dài hơn giới hạn sinh lời nói, hãy tạo một tài liệu bằng cách sử dụng POST /v1/documents và xuất âm thanh của nó từ ứng dụng.
Tài liệu: chia sẻ, dịch, xuất
Các tài liệu được tuần tự hóa bao gồm visibility và share_url (null khi tư nhân). PUT /v1/documents/{id} chấp nhận visibility để công khai một trang chỉ đọc không được liệt kê tại /share/document/{id}, và is_archived để lưu trữ hoặc khôi phục. Các trang chia sẻ chỉ là văn bản. Chúng không phát âm thanh được tính tiền.
POST /v1/documents/{id}/translate tạo một phiên bản dịch mới. Nó tính tiền cùng ví tín dụng như xuất MP3 (0.5 tín dụng cho mỗi 30 giây lời nói được ước tính) và trả lời 402 khi ví không đủ. Nó trả lời 503 khi dịch chưa được cấu hình hoặc bị ngắt kết nối.
GET /v1/documents/{id}/export?format=pdf|docx|txt|csv|srt|vtt tải xuống phiên bản hiện tại dưới dạng tệp đính kèm. Thêm timestamps=1 để bao gồm thời gian phần trong PDF, DOCX, TXT và CSV. SRT và VTT cần một bản ghi âm hoặc thời gian câu hoàn chỉnh. Thông tin thời gian trong text được lưu trữ trên GET /v1/documents/{id} giữ các tiêu đề thời gian bản ghi âm. Ẩn chúng chỉ là một tùy chọn của người đọc ứng dụng.