Uso automatizado

Abrir uma conta Hushscript costumava exigir uma pessoa, pelo menos uma vez. Isso já não é a história toda. Um fluxo com pagamento primeiro deixa um agente abrir a própria conta, financiá-la e operá-la, sem nenhum titular humano em nenhum ponto do processo. /developers e /mcp documentam as duas interfaces que essa conta passa a usar depois; esta página é o guia para conseguir uma.

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-08-01",
    "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 a 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, e o pagamento retido é reembolsado pela varredura descrita abaixo, não devolvido por meio de uma consulta.

Conclua o checkout no seu próprio navegador

checkout_url é uma página hospedada do Stripe Checkout. É a única etapa de todo esse fluxo que precisa de um navegador, 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; o Stripe vê. A janela para concluir o checkout e depois reivindicar a conta é de 30 minutos, o expires_at acima.

Um cadastro que é pago mas nunca reivindicado é reembolsado automaticamente por uma varredura de hora em hora, cerca de uma hora depois que essa janela de 30 minutos se fecha. O reembolso é integral, porque os minutos só são creditados a um saldo no momento da reivindicação, então um cadastro nunca reivindicado nunca teve nenhum para consumir.

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 é de uso único. Isso cria exatamente uma conta, com uma identidade de login sintética e sem resolução por trás dela, concede o pacote pago exatamente uma vez mesmo que a requisição seja repetida, e emite exatamente um PAT: o valor pat acima, também mostrado exatamente uma vez.

Um segredo errado, um signup_id desconhecido, um cadastro já reivindicado, um reembolsado e um expirado 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, não uma lacuna: a conta já tinha sido paga antes mesmo de existir.

Compre mais minutos

Daqui em diante a conta se comporta como qualquer outra, sobre a mesma 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, e compartilha um limite mais apertado de 60 requisições por minuto por conta com a rota de salvar cartão, antes da chamada ao Stripe que qualquer uma das duas faz.

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 queima 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.

Transcreva

Enviar e transcrever é o mesmo fluxo multipart de qualquer outra conta.

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 atomicamente um sucessor e revoga o token que autenticou a requisição, então o PAT antigo falha já na próxima chamada feita com ele. 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.

Erros

Estes quatro são específicos de contas de agente e nunca são alcançados por uma conta de pessoa:

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 puxa da mesma cota, então rotacionar um PAT não dá ao sucessor uma cota nova. As duas escritas de faturamento, salvar um cartão e comprar um pacote, compartilham um limite mais apertado de 60 por minuto por conta, antes da chamada ao Stripe que qualquer uma das duas faz. O teto de compra de 24 horas acima é contado da mesma forma, por conta em vez de 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.