Visão geral da API

A API do Speechdash permite que sua própria aplicação crie documentos e gere fala com as mesmas vozes do aplicativo. Tudo o que você criar por meio da API também aparecerá em sua biblioteca. Áudios e transcrições de vídeo finalizados criados no aplicativo aparecem como documentos da biblioteca também (source é transcription, com um transcript_id). Não há um recurso REST /transcripts: use os endpoints de documentos. A API não inicia tarefas de transcrição.

URL base:

https://api.speechdash.com/v1

Verificação de saúde (sem chave de API): GET https://api.speechdash.com/health

O contrato legível por máquina está publicado em https://api.speechdash.com/v1/openapi.json, então você pode gerar um cliente para sua linguagem.

Endpoints

Páginas interativas OpenAPI: Conta, Documentos, Áudio, Vozes.

Servidor MCP (para assistentes de IA)

Se você usa Cursor, Claude Desktop ou outro cliente MCP, pode adicionar o servidor MCP oficial do Speechdash em vez de chamar HTTP diretamente. Ele expõe a mesma biblioteca (incluindo transcrições finalizadas), tradução, exportação, vozes, instantâneo da conta e síntese de fala não em fluxo como ferramentas suportadas pelas mesmas chaves de API e faturamento como neste guia. A síntese de fala em fluxo permanece no REST.

Veja Servidor MCP para a lista completa de ferramentas e configuração (stdio ou Streamable HTTP). Você também pode ler o Agents hub no site de marketing para documentos legíveis por máquina direcionados a sistemas de IA. Usuários finais podem começar com Chaves de API e MCP neste Centro de Ajuda.

Criar uma chave de API

Você pode manter até 10 chaves ativas, renomeá-las a qualquer momento e ver quando cada uma foi usada pela última vez. Revogar uma chave interrompe suas solicitações imediatamente.

Autenticar uma solicitação

Envie a chave como um token bearer:

curl https://api.speechdash.com/v1/me \
 -H "Authorization: Bearer sh_live_sua_chave"

Solicitações sem uma chave válida respondem com 401 e o código unauthorized.

GET /me retorna seu ID de conta, email, plano e saldo da carteira (wallet_cents e display_credits), além de metadados sobre a chave de API usada. Use isso para verificar uma chave após a configuração (por exemplo, no Zapier).

POST /documents e POST /audio/speech aceitam um cabeçalho opcional Idempotency-Key. Tentar novamente a mesma chave com o mesmo corpo reprodura a primeira resposta bem-sucedida por 24 horas, então um pequeno problema de rede não cria um segundo documento ou fatura a fala duas vezes. Se uma resposta de fala for muito grande para armazenar, uma tentativa de repetição com a mesma chave responde 409 em vez de regenerar (a solicitação original já foi faturada). Um desconexão do cliente em /audio/speech responde 204, liquida qualquer áudio já produzido e libera a chave para que uma repetição possa regenerar. Os endpoints de áudio em fluxo rejeitam o cabeçalho.

Créditos

A síntese de fala gasta créditos da mesma carteira do aplicativo: 0,5 créditos (1 centavo da carteira) por cada 30 segundos iniciados de áudio gerado. Cada solicitação mantém uma estimativa (mais uma pequena margem) antes que a geração comece, então é liquidada para o áudio que foi realmente produzido. O crédito retido não usado é reembolsado; cada solicitação liquidada aparece em Configurações → Uso de créditos como Síntese de fala da API. O campo billed_credits nas respostas da API é em centavos da carteira (2 centavos = 1 crédito exibido). Se um fluxo for interrompido no meio, as frases já entregues ainda são faturadas.

Se o seu saldo não puder cobrir o crédito retido, a API responde 402 com o código payment_required antes de gerar qualquer coisa.

Criar documentos não gasta créditos, mas conta para o limite diário de documentos do seu plano (Gratuito: 3 por dia; Unlimited: sem limite diário) e limites de duração de upload. A exportação de arquivos não gasta créditos.

Faturamento vs reprodução em nuvem no aplicativo

A reprodução em nuvem Cloud no aplicativo reutiliza o cache de frases por documento: reproduzir uma frase que já foi gerada no servidor pode custar 0 créditos exibidos. Os endpoints de fala REST e MCP sempre sintetizam áudio fresco e faturam por cada 30 segundos iniciados à mesma taxa quando a geração ocorre. Não há cache de reprodução na síntese da API ou MCP.

Limites

Os limites de taxa são contados por conta, não por chave, então chaves extras não aumentam sua cota. Cada resposta carrega X-Request-ID, e /documents além de /audio/* também retornam X-RateLimit-Limit, X-RateLimit-Remaining, e X-RateLimit-Reset. Cite X-Request-ID quando entrar em contato com o suporte.

Solicitações de fala também têm um limite de paralelismo: uma quarta solicitação simultânea responde 429 enquanto três ainda estão em execução, então uma integração não pode monopolizar a síntese. Retente 429 e 503 após o cabeçalho Retry-After.

Para conteúdo mais longo que os limites de fala, crie um documento com POST /v1/documents e exporte seu áudio a partir do aplicativo.

Documentos: compartilhar, traduzir, exportar

Documentos serializados incluem visibility e share_url (nulo quando privado). PUT /v1/documents/{id} aceita visibility para publicar uma página de leitura somente para visualização não listada em /share/document/{id}, e is_archived para arquivar ou restaurar. Páginas compartilhadas são apenas de texto. Elas não reproduzem áudio faturado.

POST /v1/documents/{id}/translate cria uma nova versão traduzida. Ela fatura a mesma carteira de créditos que a exportação para MP3 (0,5 créditos por cada 30 segundos iniciados de fala estimada) e responde 402 quando a carteira está curta. Ela responde 503 quando a tradução não está configurada ou fora do ar.

GET /v1/documents/{id}/export?format=pdf|docx|txt|csv|srt|vtt baixa a versão atual como um anexo. Adicione timestamps=1 para incluir tempos de seção em PDF, DOCX, TXT e CSV. SRT e VTT precisam de uma transcrição ou tempos de frases completos. O texto armazenado em GET /v1/documents/{id} mantém cabeçalhos de marca de hora da transcrição. Esconder esses cabeçalhos é apenas um controle do leitor do aplicativo.

Relacionados