Vista general de la API
Llame a Speechdash desde su propia aplicación y cree las claves API que la autorizan.
La API de Speechdash le permite a su propia aplicación crear documentos y generar voz con las mismas voces que la aplicación. Todo lo que cree a través de la API también aparece en su biblioteca. Los audios y transcripciones de video terminados creados en la aplicación aparecen como documentos de la biblioteca también (source es transcripción, con un transcript_id). No existe el recurso REST /transcripts: use los endpoints de documentos. La API no inicia trabajos de transcripción.
URL base:
https://api.speechdash.com/v1Verificación de salud (sin clave API): GET https://api.speechdash.com/health
El contrato legible por máquina está publicado en https://api.speechdash.com/v1/openapi.json, por lo que puede generar un cliente para su lenguaje.
Endpoints
| Método | Ruta | Propósito |
|---|---|---|
GET | /health | Salud del servicio (no bajo /v1) |
GET | /v1/openapi.json | Documento OpenAPI 3.1 |
GET | /v1/me | Cuenta, plan y billetera |
GET | /v1/documents | Lista de documentos de la biblioteca, incluyendo transcripciones terminadas |
POST | /v1/documents | Crea un documento de texto (source=api) |
GET | /v1/documents/{document_id} | Lee un documento y su texto |
PUT | /v1/documents/{document_id} | Actualiza el título, texto, idioma, is_archived, o visibility |
DELETE | /v1/documents/{document_id} | Elimina un documento |
POST | /v1/documents/{document_id}/translate | Nueva versión traducida (misma tarifa que la exportación a MP3) |
GET | /v1/documents/{document_id}/export | Descarga pdf, docx, txt, csv, srt, o vtt |
POST | /v1/audio/speech | Sintetiza hasta 5,000 caracteres (JSON + audio) |
POST | /v1/audio/stream | Transmite WAV, hasta 20,000 caracteres |
POST | /v1/audio/stream/with-timestamps | SSE con audio por oración y marcas |
GET | /v1/voices | Catálogo de voces |
GET | /v1/voices/{voice_id} | Una configuración de voz predeterminada |
Páginas interactivas de OpenAPI: Cuenta, Documentos, Audio, Voces.
Servidor MCP (para asistentes de IA)
Si usa Cursor, Claude Desktop o cualquier otro cliente MCP, puede agregar el servidor MCP oficial de Speechdash en lugar de llamar directamente a HTTP. Expose la misma biblioteca (incluyendo transcripciones terminadas), traducción, exportación, voces, instantánea de la cuenta y síntesis de voz no en streaming como herramientas respaldadas por las mismas claves API y facturación que esta guía. La síntesis de voz en streaming sigue en REST.
Consulte Servidor MCP para obtener la lista completa de herramientas y configuración (stdio o Streamable HTTP). También puede leer el Agents hub en el sitio de marketing para documentos legibles por máquina dirigidos a sistemas de IA. Los usuarios finales pueden comenzar desde Claves API y MCP en este Centro de Ayuda.
Crear una clave API
Abra Configuración → API.
Haga clic en Nueva clave y déle un nombre que indique dónde se usará, como Servidor de producción.
Copie la clave de inmediato. Solo se almacena su prefijo, por lo que se muestra una vez y nunca más.
Una clave actúa sobre su cuenta. Guárdela en su servidor, nunca en un navegador, una aplicación móvil o un repositorio público. Si una clave se filtra, revóquela desde Configuración → API y cree una nueva.
Puede mantener hasta 10 claves activas, renombrarlas en cualquier momento y ver cuándo se usó cada una. Revocar una clave detiene sus solicitudes de inmediato.
Autenticar una solicitud
Envía la clave como un token de portador:
curl https://api.speechdash.com/v1/me \
-H "Authorization: Bearer sh_live_tu_clave"Las solicitudes sin una clave válida responden con 401 y el código no autorizado.
GET /me devuelve su ID de cuenta, correo electrónico, plan y saldo de la billetera (wallet_cents y display_credits), además de metadatos sobre la clave API utilizada. Úsela para verificar una clave después de la configuración (por ejemplo, en Zapier).
POST /documents y POST /audio/speech aceptan un encabezado opcional Idempotency-Key. Reintentar la misma clave con el mismo cuerpo vuelve a reproducir la primera respuesta exitosa durante 24 horas, por lo que un parpadeo en la red no crea un segundo documento ni factura la voz dos veces. Si una respuesta de voz es demasiado grande para almacenarse, una reintención con la misma clave responde 409 en lugar de regenerar (la solicitud original ya fue facturada). Una desconexión del cliente en /audio/speech responde 204, liquida cualquier audio ya producido y libera la clave para que una reintención pueda regenerar. Los endpoints de audio en streaming rechazan el encabezado.
Créditos
La síntesis de voz gasta créditos de la misma billetera que la aplicación: 0.5 créditos (1 centavo de la billetera) por cada 30 segundos de audio generado iniciado. Cada solicitud mantiene una estimación (más un pequeño margen) antes de que comience la generación, luego se liquida al audio que realmente se produjo. El crédito retenido sin uso se reembolsa; cada solicitud liquidada aparece en Configuración → Uso de créditos como Síntesis de voz de la API. El campo billed_credits en las respuestas de la API son centavos de la billetera (2 centavos = 1 crédito de visualización). Si un stream se interrumpe a mitad de camino, las oraciones ya entregadas siguen facturándose.
Si su saldo no puede cubrir el crédito retenido, la API responde 402 con el código payment_required antes de generar algo.
Crear documentos no gasta créditos, pero cuenta hacia el límite diario de documentos de su plan (Gratis: 3 por día; Unlimited: sin límite diario) y los límites de duración de carga. La exportación de archivos no gasta créditos.
Facturación vs reproducción en la nube dentro de la aplicación
La reproducción en la nube dentro de la aplicación reutiliza el caché de oraciones por documento: reproducir una oración que ya se generó en el servidor puede costar 0 créditos de visualización. Los endpoints de voz REST y MCP siempre sintetizan audio fresco y facturan por cada 30 segundos iniciados a la misma tasa cuando ocurre la generación. No hay caché de reproducción en la síntesis de la API o MCP.
Límites
| Límite | Valor |
|---|---|
Solicitudes a /documents | 120 por minuto, por cuenta |
Solicitudes a /audio/* | 60 por minuto, por cuenta |
| Solicitudes de voz en paralelo | 3 por cuenta |
POST /audio/speech input | 5,000 caracteres |
POST /audio/stream input | 20,000 caracteres |
| Texto del documento | 500,000 caracteres |
| Claves API activas | 10 |
Los límites de tasa se cuentan por cuenta, no por clave, por lo que las claves adicionales no aumentan su cuota. Cada respuesta lleva X-Request-ID, y /documents junto con /audio/* también devuelve X-RateLimit-Limit, X-RateLimit-Remaining, y X-RateLimit-Reset. Cite X-Request-ID cuando contacte al soporte.
Las solicitudes de voz también tienen un límite de paralelismo: una cuarta solicitud simultánea responde 429 mientras tres aún están en ejecución, por lo que una sola integración no puede monopolizar la síntesis. Reintente 429 y 503 después del encabezado Retry-After.
Para contenido más largo que los límites de voz, cree un documento con POST /v1/documents y exporte su audio desde la aplicación.
Documentos: compartir, traducir, exportar
Los documentos serializados incluyen visibility y share_url (nulo cuando es privado). PUT /v1/documents/{id} acepta visibility para publicar una página de solo lectura no enumerada en /share/document/{id}, y is_archived para archivar o restaurar. Las páginas compartidas son solo de texto. No reproducen audio facturado.
POST /v1/documents/{id}/translate crea una nueva versión traducida. Factura la misma billetera de créditos que la exportación a MP3 (0.5 créditos por cada 30 segundos de voz estimada) y responde 402 cuando la billetera está corta. Responde 503 cuando la traducción no está configurada o está caída.
GET /v1/documents/{id}/export?format=pdf|docx|txt|csv|srt|vtt descarga la versión actual como un archivo adjunto. Agregue timestamps=1 para incluir tiempos de sección en PDF, DOCX, TXT y CSV. SRT y VTT necesitan una transcripción o tiempos completos de oraciones. El texto almacenado en GET /v1/documents/{id} mantiene los encabezados de marca de tiempo de la transcripción. Ocultarlos es una opción de ajuste solo para el lector de la aplicación.