Transcrição automática para agentes e scripts

A transcrição automática no Hushscript transforma uma gravação de áudio existente em uma transcrição editável. No app de navegador, você também pode começar com um vídeo local: o Hushscript prepara o áudio dele no seu dispositivo e envia só esse áudio para o reconhecimento online. Você mesmo revisa e corrige o resultado: este não é um serviço de transcrição revisado por humanos nem certificado.

Como funciona a transcrição automática

1. Prepare a gravação. Use um arquivo de áudio, importe um link de áudio compatível ou grave sua voz no app de navegador. Para gravações de vídeo, escolha um arquivo local para que o app prepare o áudio no seu dispositivo.
2. Envie e aguarde a transcrição. O app cuida do envio e do status. Um agente pode enviar áudio preparado em partes pela API REST ou usar as ferramentas MCP com escopo, e depois consultar o job até a transcrição ficar pronta.
3. Revise e exporte. Edite a transcrição e os rótulos de falantes no app, ou recupere o texto pela API. O token de um agente também pode exportar a transcrição dentro dos escopos concedidos.

Software de transcrição automática para áudio e vídeo

O software de transcrição automática do Hushscript transforma fala gravada em texto que você pode pesquisar, editar e exportar. A entrada de gravação do app também permite capturar uma gravação de voz antes da transcrição. Para um arquivo de gravação avulso, sem transcrição, use o gravador de voz gratuito.

A transcrição automática de vídeo segue o mesmo fluxo de texto depois que o app extrai ou converte o áudio localmente. O exemplo de envio REST abaixo começa com áudio preparado; para entregar ao app seu arquivo de vídeo local, use o fluxo do navegador em vídeo para texto.

Posso testar a transcrição automática de graça?

Sim. A prévia pública transcreve até cinco minutos de um arquivo, link de áudio compatível ou gravação no navegador antes do login, e um vídeo local funciona quando o navegador prepara o áudio dele. A transcrição completa exige uma conta: uma conta pessoal elegível recebe 30 minutos grátis após a verificação do cartão (veja os preços para saber como isso funciona), enquanto uma conta de máquina não recebe os minutos de boas-vindas e começa com o pacote que compra no cadastro.

Automatize transcrições com a API ou o MCP

O app de navegador serve para trabalhar diretamente com gravações. Para automatizar transcrições, a API REST e o servidor MCP permitem que um agente envie áudio preparado, consulte jobs, recupere transcrições e exporte resultados. Um agente pode abrir a própria conta com um fluxo de pagamento primeiro, sem um titular humano; o checkout hospedado ainda precisa de um navegador, e a emissora do cartão pode exigir uma etapa de autenticação. Uma pessoa pode, em vez disso, criar um token com escopo a partir de uma conta existente no app. Este guia acompanha a conta de máquina do cadastro até a rotação da credencial.

Cadastro

POST /v1/agent/accounts abre um cadastro sem interface. Ainda não existe conta, nem cookie, nem token: só uma compra pendente.

curl -X POST https://api.hushscript.com/v1/agent/accounts \
  -H "Content-Type: application/json" \
  -d '{
    "contact_email": "ops@example-agent.dev",
    "pack_id": "300min",
    "accept_terms_version": "2026-10-20",
    "agent": {
      "name": "research-crawler",
      "platform": "langgraph",
      "contact_url": "https://example-agent.dev/bots/research-crawler"
    }
  }'

{
  "signup_id": "hsr1:eu:4c3a1f9e7b2d4e6f8a0c1b2d3e4f5061",
  "claim_secret": "cs_9f3d2a1b7e6c4f5a8b9d0e1f2a3b4c5d",
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_a1B2c3D4e5F6",
  "pack": "300min",
  "amount": 599,
  "currency": "usd",
  "expires_at": 1789112400
}

contact_email serve só para recibos e avisos, nunca para login. pack_id é um de 45min, 300min, 900min, 1800min, 6000min; nunca envie amount nem currency você mesmo, os dois são derivados do pacote no servidor. Só os dois pacotes menores, 45min e 300min, podem ser comprados no cadastro. Um pack_id maior é recusado, e a recusa traz details.allowed_packs listando o que essa conta pode comprar agora, para que quem chamou possa tentar de novo sem adivinhar. O resto da escada libera com a idade, não com o volume: veja O que uma conta nova pode comprar abaixo. accept_terms_version precisa bater exatamente com a versão de política atual do servidor, ou a chamada falha com policy_version_stale, que nomeia o valor atual no corpo da resposta. Uma dica opcional de data_region só é respeitada quando concorda com a região que sua localização de rede já implica. Um dry_run: true opcional valida tudo sem sessão do Stripe e sem cobrança; seu signup_id vem com o prefixo dry_ e nunca pode ser reivindicado.

claim_secret aparece exatamente uma vez, nesta resposta. O Hushscript guarda só o hash dele. Perdê-lo antes da chamada de reivindicação significa perder o cadastro: não existe rota de recuperação para um segredo de reivindicação. Um cadastro pago e não reivindicado entra no processo de reembolso descrito abaixo; não pode ser recuperado por meio de uma consulta.

Conclua o checkout no seu próprio navegador

checkout_url é uma página hospedada do Stripe Checkout. O cadastro precisa de um navegador para esta etapa, e não precisa ser o navegador de uma pessoa: um agente pode conduzi-la com a própria automação (preencher os campos do cartão, enviar, seguir o redirecionamento). O Hushscript nunca vê os dados do cartão de qualquer forma; quem vê é o Stripe. A janela para concluir o checkout e depois reivindicar a conta é de 30 minutos, o expires_at acima.

Uma varredura de hora em hora verifica os cadastros pagos e não reivindicados depois da janela de reivindicação de 30 minutos e de mais uma hora de tolerância. Ela tenta um reembolso integral, porque os minutos só são creditados na reivindicação. Tentativas de reembolso que falham são repetidas e podem exigir tratamento manual; não há garantia de que o reembolso chegue em um horário específico.

Reivindique a conta

POST /v1/agent/accounts/{signup_id}/claim transforma um cadastro pago e não reivindicado em uma conta de verdade, em uma única chamada.

curl -X POST https://api.hushscript.com/v1/agent/accounts/hsr1:eu:4c3a1f9e7b2d4e6f8a0c1b2d3e4f5061/claim \
  -H "Content-Type: application/json" \
  -d '{"claim_secret": "cs_9f3d2a1b7e6c4f5a8b9d0e1f2a3b4c5d"}'

{
  "user_id": "usr_7d1a2b3c4d5e6f708192a3b4c5d6e7f8",
  "pat": "hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170",
  "scopes": [
    "transcripts:read",
    "transcripts:write",
    "transcribe",
    "account:read",
    "export",
    "billing",
    "pat:rotate"
  ],
  "balance_seconds": 18000
}

Reivindicar cria exatamente uma conta, com uma identidade de login sintética, que não corresponde a nenhum endereço real, e concede o pacote pago exatamente uma vez, por mais vezes que a requisição seja repetida. Emite um PAT: o valor pat acima.

Se a resposta se perder, repita a chamada com o mesmo claim_secret. Até uma hora depois da reivindicação, e enquanto o token emitido nunca tiver sido usado, a nova tentativa retorna 201 para a mesma conta, com o mesmo formato de resposta e um pat novo. O token perdido deixa de funcionar. Depois do primeiro uso do token, ou passada essa hora, uma nova tentativa responde agent_claim_invalid. Uma nova tentativa que se sobreponha a uma reivindicação ainda em andamento pode receber 429 rate_limited com um cabeçalho Retry-After; tente de novo depois desse intervalo.

Esse primeiro token pode transcrever, ler e editar transcrições, exportar, consultar o saldo da conta, comprar minutos e rotacionar a si mesmo. Ele não concede escopos de Insights, contexto, organização nem escrita de configurações. O servidor MCP só oferece as ferramentas cobertas pelos escopos do token.

Um segredo errado, um signup_id desconhecido, um cadastro reembolsado, um expirado e uma reivindicação repetida cujo token já foi usado ou cuja hora passou respondem todos com o mesmo erro agent_claim_invalid. Não há como quem chamou distinguir esses casos pela resposta, de propósito. Só depois que o próprio segredo é validado é que o estado do pagamento entra em jogo: uma Checkout Session que ainda não foi liquidada responde wrong_state em vez disso.

O balance_seconds acima é todo o saldo inicial. Contas de agente não recebem bônus de boas-vindas nem minutos grátis por verificação de cartão como uma primeira conta de pessoa recebe; elas começam do zero, só com o pacote que pagaram. Isso é deliberado: a conta já tinha sido paga antes mesmo de existir.

Compre mais minutos

A partir daqui a conta usa a superfície /v1/ que /developers documenta por completo.

curl -X POST https://api.hushscript.com/v1/billing/purchase \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170" \
  -H "Content-Type: application/json" \
  -d '{
    "pack": "300min",
    "quick_payment_method_id": "pm_1PqR2sT3uV4wX5yZ",
    "idempotency_key": "purchase-2026-09-11-01"
  }'

{
  "balance_seconds": 36000
}

Isso exige o escopo billing, que a resposta de reivindicação acima já concedeu. A reivindicação também ativa o faturamento no token e na conta; um token criado por uma pessoa precisa do escopo billing e dos dois interruptores de faturamento ativados. As chamadas de faturamento por PAT compartilham um limite mais apertado de 60 requisições por minuto por conta nas rotas de faturamento que chamam o Stripe, antes das requisições ao Stripe.

O que uma conta nova pode comprar

O tamanho do pacote libera com a idade dos pagamentos liquidados, não com quanto a conta gasta. Uma compra só conta para o próximo nível quando já passou 7 dias da própria data de pagamento, então uma conta recém-criada não consegue chegar aos pacotes grandes comprando rápido.

Uma compra recusada nomeia o conjunto atual em details.allowed_packs em vez de falhar às cegas. A chamada de cadastro aplica a primeira linha dessa tabela, e é por isso que o guia acima compra 300min e não algo maior. Separado da escada, um teto de consumo contínuo de 24 horas limita a velocidade com que um saldo que ainda não passou da janela de contestação pode ser gasto. A compra do cadastro conta para as três tentativas de compra da conta em 24 horas contínuas; tentativas recusadas após a reserva também contam.

Transcreva

Enviar e transcrever é o mesmo fluxo multipart de qualquer outra conta. O exemplo de API envia áudio preparado; ele não envia o arquivo de origem de um vídeo local.

curl -X POST https://api.hushscript.com/v1/uploads \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170" \
  -H "Content-Type: application/json" \
  -d '{
    "size_bytes": 48213504,
    "duration_seconds": 1860,
    "title": "weekly-standup-2026-09-11",
    "idempotency_key": "upload-2026-09-11-01"
  }'

{
  "job_id": "job_3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d",
  "part_urls": [
    { "n": 1, "url": "https://r2.hushscript.com/uploads/job_3a2b1c0d.../part-1?X-Amz-Signature=..." }
  ]
}

Envie cada parte com PUT para a sua URL pré-assinada, depois envie um POST para o /complete do mesmo job com o n e o etag de cada parte enviada dessa forma. Em seguida, consulte o job periodicamente:

curl https://api.hushscript.com/v1/jobs/job_3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170"

{
  "id": "job_3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d",
  "state": "done",
  "transcript_id": "trs_6f5e4d3c2b1a0908f7e6d5c4b3a29180"
}

curl https://api.hushscript.com/v1/transcripts/trs_6f5e4d3c2b1a0908f7e6d5c4b3a29180 \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170"

{
  "id": "trs_6f5e4d3c2b1a0908f7e6d5c4b3a29180",
  "language": "en",
  "duration_seconds": 1860,
  "body": "..."
}

Rotacione a credencial

Uma conta de máquina não tem senha nem uma caixa de e-mail utilizável, então não existe um caminho de “esqueci minha senha” se um PAT vazar ou simplesmente precisar ser trocado. A rotação é esse caminho.

curl -X POST https://api.hushscript.com/v1/agent/credentials/rotate \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170"

{
  "pat": "hsr1:eu:pat.p9q8r7.1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
  "pat_id": "p9q8r7",
  "scopes": [
    "transcripts:read",
    "transcripts:write",
    "transcribe",
    "account:read",
    "export",
    "billing",
    "pat:rotate"
  ],
  "expires_at": null
}

A chamada não leva corpo. Ela emite um sucessor para o token que autenticou a requisição. O sucessor mantém os escopos, a permissão de faturamento, o nome, o rótulo de cliente e a política de expiração do antecessor. Essa rota não toca em nada além do próprio token de quem chamou: ela não consegue listar, emitir nem revogar nenhuma outra credencial da conta. É o único caminho de recuperação de credencial que uma conta de máquina tem, então rotacione antes de descartar o token antigo, não depois.

O token antigo não é revogado de imediato. Depois da rotação, ele serve para uma única coisa: chamar a rotação de novo. Isso dura até o novo token fazer a primeira requisição bem-sucedida ou até passar uma hora, o que ocorrer primeiro. Em qualquer outra rota, o token antigo responde 401 na hora.

Se a resposta com o novo token se perder, chame a rotação de novo com o token antigo enquanto o novo estiver sem uso. Você recebe um segredo novo para o mesmo pat_id, e o segredo novo anterior deixa de funcionar.

Guarde o token antigo até o novo ter funcionado uma vez. Depois, faça logo uma chamada com o novo token, como GET /v1/account. Essa primeira requisição bem-sucedida aposenta o token antigo de vez.

Erros

Esses erros cobrem o cadastro de agentes e os controles de compra. O teto de compras também vale para compras por PAT em uma conta de pessoa; uma compra em sessão humana fica isenta.

Depois que o próprio segredo de reivindicação é validado, uma Checkout Session não paga responde wrong_state (4001) em vez de agent_claim_invalid. O catálogo completo está no documento OpenAPI.

Limites

As chamadas são limitadas a 1.200 por minuto. Para uma conta de agente, essa cota pertence à conta, não ao token individual: toda credencial na linhagem de rotação usa a mesma cota, então rotacionar um PAT não dá ao sucessor uma cota nova. As chamadas de faturamento por PAT que chegam ao Stripe compartilham um limite mais apertado de 60 por minuto por conta. Isso inclui configuração e compra, mudança e remoção do cartão padrão e falhas de cache na lista de cartões; a verificação acontece antes da chamada ao Stripe. O teto de compra de 24 horas acima é contado da mesma forma, por conta e não por credencial.

Saiba mais

Esta página cobre o ciclo de vida da conta: abrir uma, financiá-la e manter sua credencial ativa. Para tudo o que a conta pode fazer depois, veja a API REST, incluindo o documento OpenAPI completo, ou o servidor MCP para a mesma conta por meio de ferramentas em vez de HTTP puro.