API do UtilNest para desenvolvedores

A API do UtilNest dá às contas Pro os mecanismos por trás do site via HTTPS: todas as calculadoras, conversores de unidades e tabelas de referência, conversões de documentos e ebooks, transcrição na nuvem, remoção de fundo e ampliação em HD e as ferramentas de IA de texto e imagem. Cada chamada custa exatamente o mesmo que a mesma ação no site e usa os mesmos limites do plano e créditos.

Chaves

Crie uma chave na página da conta (plano Pro). Ela começa com un_live_…, aparece uma única vez e guardamos apenas um hash dela; revogue quando quiser na mesma página. A chave funciona enquanto a conta estiver no Pro. Envie-a como token bearer:

curl https://api.utilnest.io/v1/me -H "Authorization: Bearer $UTILNEST_KEY"

Guarde as chaves no seu servidor; não as coloque em páginas web nem em apps que você distribui.

Calculadoras, conversores e tabelas

GET /v1/utilities lista as utilidades disponíveis, com campos e valores padrão. POST /v1/run/{utilidade} executa uma com um corpo JSON; os campos omitidos usam o padrão. Essas chamadas não gastam créditos.

curl https://api.utilnest.io/v1/run/units.length.miles-to-km \
  -H "Authorization: Bearer $UTILNEST_KEY" -H "Content-Type: application/json" \
  -d '{"value": 26.2}'
# {"utility":"units.length.miles-to-km","result":42.1648128}

curl https://api.utilnest.io/v1/run/calculators.finance.br.inss-calculator \
  -H "Authorization: Bearer $UTILNEST_KEY" -H "Content-Type: application/json" -d '{"salary": 5000}'

O esquema de entrada de cada utilidade está no documento OpenAPI 3.1, gerado do mesmo registro que o site usa.

Conversões de documentos e ebooks

O mesmo fluxo do site: crie um upload, envie os bytes para o link recebido, inicie a conversão e baixe o resultado. Valem os limites do Pro (tamanho de arquivo, janelas de upload, conversões por dia e tempo de guarda).

# 1. Upload (arquivos pequenos recebem um link PUT; grandes, multipart)
curl https://api.utilnest.io/v1/uploads -H "Authorization: Bearer $UTILNEST_KEY" \
  -H "Content-Type: application/json" -d '{"name": "contrato.pdf", "size": 182044}'
curl -X PUT "$URL" -H "Content-Type: application/pdf" --data-binary @contrato.pdf
curl -X POST https://api.utilnest.io/v1/uploads/$FILE/complete -H "Authorization: Bearer $UTILNEST_KEY"

# 2. Converter: handlers office.pdf, pdf.docx, pdf.xlsx, ebook.pdf, ebook.epub
curl https://api.utilnest.io/v1/jobs -H "Authorization: Bearer $UTILNEST_KEY" \
  -H "Content-Type: application/json" -d '{"fileId": "'$FILE'", "handler": "pdf.docx", "options": {"to": "docx"}}'

# 3. Consulte GET /v1/jobs/{id} até terminar e peça o link de download do arquivo gerado
curl https://api.utilnest.io/v1/files/$OUTPUT/download -H "Authorization: Bearer $UTILNEST_KEY"

IA na nuvem

Rodam em https://utilnest.io/api/ai/… com a mesma chave e descontam créditos pelo custo real do modelo, como no site:

Saldo e o que resta no mês: GET https://api.utilnest.io/v1/usage.

Limites, erros e novas tentativas

• Taxa: 120 requisições por minuto por chave (429 com Retry-After acima disso), além dos limites do plano.
• Idempotência: envie Idempotency-Key: <seu id> num POST ao host da API; repetir em até 24 horas devolve a primeira resposta (com Idempotent-Replayed: true) em vez de executar de novo. A mesma chave com outro corpo recebe 422.
• Erros vêm em JSON: {"error": "código", "message": "…"}. Os mais comuns: invalid-key (401), pro-required (403), rate (429), credits (402, com o saldo), unknown-utility (404), invalid-input (400).
• Logs: registramos hora, caminho, status e id da chave de cada chamada, nunca o que você envia ou recebe.

Os termos de uso valem para a API; acesso automatizado só pela API.