Documentação da API

Comece por aqui

A API Jusneural 2.0 Pro recebe uma pergunta ou documento e entrega uma resposta textual em JSON. O uso é independente dos planos da plataforma: qualquer pessoa cadastrada pode criar uma chave e recarregar a carteira da API.

1. Crie uma chave no painel e guarde-a em uma variável de ambiente no seu servidor.
2. Adicione créditos à carteira da API. A recarga mínima é R$ 300,00.
3. Escolha a linguagem e a operação no gerador de exemplos. Ajuste a instrução, a pesquisa web e o tipo de arquivo.
4. Gere e guarde uma Idempotency-Key por operação antes do envio. Reutilize-a em consultas de status e repetições.

A chamada de geração é síncrona. O serviço limita o processamento a 100 segundos desde a entrada da requisição e reserva tempo para concluir os registros, com limite de resposta de 110 segundos. Configure o timeout do cliente para 120 segundos. A resposta é entregue inteira, sem streaming. A consulta GET acompanha a operação; ela não cria uma fila nem retoma uma geração interrompida.

Exemplos de integração

Escolha uma linguagem e o tipo de operação. Os exemplos usam variáveis de ambiente e mostram uma chamada completa. Gerar, copiar e baixar o código não executa chamadas nem consome créditos.

# Defina as variáveis no ambiente antes de executar.
: "${JUSNEURAL_API_KEY:?Defina sua chave da API}"
: "${JUSNEURAL_OPERATION_ID:?Defina um ID único e reutilize-o nas repetições}"
payload='{
  "model": "jusneural-2.0-pro",
  "messages": [
    {
      "role": "user",
      "content": "Explique os requisitos da tutela de urgência no processo civil brasileiro."
    }
  ],
  "instruction": "Responda de forma objetiva, com fundamentação jurídica e linguagem formal.",
  "web": false,
  "max_output_tokens": 8192,
  "max_cost_cents": 1000
}'

printf '%s' "$payload" | curl --request POST 'https://app.jusneural.com/api/api-jusneural/consultar' \
  --connect-timeout 10 --max-time 120 --fail-with-body \
  --header "Authorization: Bearer $JUSNEURAL_API_KEY" \
  --header "Idempotency-Key: $JUSNEURAL_OPERATION_ID" \
  --header 'Content-Type: application/json' \
  --data-binary @-

Execute as chamadas no servidor. A chave secreta deve ficar em uma variável de ambiente ou gerenciador de segredos. Em falha de rede, consulte a operação antes de repetir o POST.

Autenticação e preparação

Execute os exemplos no servidor da sua aplicação. Não inclua a chave em páginas públicas, aplicativos distribuídos ou repositórios. Use HTTPS na integração. Os exemplos leem a chave do ambiente e não incluem credenciais pessoais no código gerado.

O botão Copiar código copia somente o exemplo selecionado. O gerador de exemplos não executa chamadas nem consome créditos. Configure JUSNEURAL_FILE para anexos e escolha o MIME correspondente. Use Salvar em PDF para baixar o guia completo com o exemplo selecionado.

Corpo da consulta

Não são aceitos campos extras, papéis system/developer, URLs de arquivos ou configurações internas. Valores inválidos retornam 400. Para continuar uma conversa, envie o histórico relevante e os anexos que ainda sejam necessários.

PDF, imagens e áudios

Multipart é recomendado para arquivos. Envie um único campo de texto payload contendo o JSON da chamada e uma parte binária por arquivo. No JSON, use attachments: [{"upload":"arquivo_1"}]. O nome arquivo_1 precisa corresponder à parte binária. Cada arquivo deve ser referenciado exatamente uma vez; não repita partes nem misture anexos base64 no payload multipart.

Deixe a biblioteca HTTP definir o Content-Type e o boundary do formulário. O MIME deve ser informado na parte binária. O filename opcional fica no JSON, aceita até 180 caracteres sem caminhos e serve apenas como identificação do anexo.

No transporte application/json, envie mime_type e data_base64: base64 puro, sem prefixo data: e sem quebras de linha. O serviço interpreta o arquivo; a sequência base64 não é cobrada como texto literal.

1. Até 4 arquivos em todo o histórico, sendo no máximo um áudio.
2. Até 5 MiB por arquivo e 10 MiB no total, antes do base64.
3. Corpo da requisição: até 16 MiB, sem compressão. Campo payload do multipart: até 2 MiB.
4. Prazo de envio do corpo: 30 segundos, incluído no prazo total da chamada. Um envio demorado reduz o tempo disponível para geração.
5. Arquivos precisam estar íntegros. PDFs devem estar sem senha. O conteúdo também precisa caber no contexto e no orçamento autorizado.

O serviço da API não armazena os anexos em disco, banco ou bucket. Eles são processados durante a chamada. A resposta pode conter trechos do material analisado e fica disponível por 24 horas para consulta e repetição.

Resposta, tokens e cobrança

O texto fica em choices[0].message.content. usage mostra o consumo confirmado de todas as etapas. billing traz valores em reais como strings decimais de oito casas; preserve a precisão ao armazená-los. Exemplo ilustrativo:

{
  "model": "jusneural-2.0-pro",
  "model_name": "Jusneural 2.0 Pro",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Resposta jurídica produzida pelo Jusneural."
      },
      "finish_reason": "stop"
    }
  ],
  "web": false,
  "usage": {
    "input_tokens": 1000,
    "output_tokens": 200,
    "total_tokens": 1200,
    "output_tokens_details": {
      "reasoning_tokens": 40
    },
    "input_tokens_details": {
      "tool_tokens": 0
    }
  },
  "billing": {
    "currency": "BRL",
    "cost_brl": "0.05543800",
    "measured_cost_brl": "0.05543800",
    "discount_brl": "0.00000000",
    "balance_brl": "299.94456200"
  },
  "request_id": "11111111-2222-4333-8444-555555555555"
}

Entrada: R$ 31,38 por milhão de tokens. Saída: R$ 120,29 por milhão. Todos os passos e novas tentativas com consumo confirmado entram na soma, inclusive quando a operação termina com erro. Não há cobrança estimada. Confira usage e billing também nas respostas de erro, quando presentes. O débito nunca supera max_cost_cents.

Idempotência, status e novas tentativas

Guarde a Idempotency-Key antes de enviar o POST. Se houver falha de conexão, consulte o GET /api/api-jusneural/solicitacoes usando o mesmo Bearer e a mesma chave de operação, sem corpo nem arquivos. Somente a chave de API que originou a chamada pode consultar o resultado.

Se o POST retornar 504 sem usage e billing, a conclusão dos registros pode estar pendente. Consulte o GET com a mesma Idempotency-Key até obter o resultado definitivo; não interprete a ausência desses campos como consumo zero. Uma resposta gerada dentro do prazo pode aparecer como completed nessa consulta se apenas o registro final tiver demorado. Não crie outro ID para recuperar a resposta.

O GET não gera tokens nem cobrança. Um resultado final de erro também é idempotente: repetir o POST com o mesmo ID recupera esse resultado. Use outro ID somente para uma nova geração, sujeita à cobrança do consumo confirmado. Mudar parâmetros ou anexos usando o mesmo ID retorna 409.

Limites por conta, compartilhados entre todas as chaves: 60 POSTs por minuto, 120 consultas de status por minuto, 3 gerações e 3 recebimentos simultâneos. Em 429, respeite Retry-After e aumente o intervalo das tentativas com uma pequena variação aleatória. Evite repetição automática ilimitada.

Erros e como resolver

{
  "error": {
    "code": "service_unavailable",
    "message": "Ocorreu um erro interno. Tente novamente com a mesma Idempotency-Key."
  },
  "request_id": "11111111-2222-4333-8444-555555555555"
}

Trate o status HTTP e error.code no código de integração. A mensagem é destinada à leitura humana. Falhas internas usam textos genéricos. Para suporte, informe os identificadores da operação; não envie sua chave secreta. Falhas do cliente ou da rede podem não trazer corpo JSON: nesses casos, consulte o status usando o ID persistido.

Créditos e pagamentos

A carteira da API é independente de assinaturas, planos e tokens dos outros serviços. Recarga mínima de R$ 300,00, por Pix ou cartão de crédito, pelo painel da API. O painel mostra saldo, consumo recente e histórico de pagamentos.

Precisa de ajuda na integração?

Fale com o suporte Jusneural e informe o request_id, o cabeçalho X-Request-Id e o identificador da operação. Preserve sua chave secreta.