Desenvolva com o niuron

API de chat completions

POST /v1/chat/completions é o endpoint de chat: classifica a requisição, escolhe um modelo, executa contra o provedor vencedor e devolve uma resposta no formato OpenAI. Aponte seu SDK OpenAI existente pra https://api.niuron.ai/v1 com uma chave de API do router (crie uma em /app/api-keys) e nada mais no seu código muda. Para decisões estruturadas com TypeSafe Jev, use a seção específica abaixo.

curl https://api.niuron.ai/v1/chat/completions \
  -H "Authorization: Bearer ar_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Explain routing in one sentence."}]
  }'

• model: "auto" deixa o roteador pontuar todo modelo elegível por custo, latência, qualidade e confiabilidade e escolher o vencedor. Fixe um nome canônico específico (ex.: gpt-4o, claude-sonnet-5) pra pular essa decisão — o formato da resposta é idêntico nos dois casos.
• response.model reporta o nome canônico realmente usado, não a string de modelo crua do provedor — seguro pra logar ou re-requisitar explicitamente.
• stream: true funciona do mesmo jeito que na OpenAI — server-sent events, um chunk por vez.

Responses API

Use POST /v1/responses com a mesma chave Bearer e os mesmos nomes de modelos do Chat Completions. Este endpoint de compatibilidade stateless traduz as requisições para o pipeline compartilhado de chat, preservando perfis, políticas da organização, retentativas, cobrança e telemetria. Ele não encaminha as requisições ao endpoint Responses nativo do provedor.

curl https://api.niuron.ai/v1/responses \
  -H "Authorization: Bearer $NIURON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "niuron/auto",
  "input": "Explain consistent hashing in two sentences.",
  "instructions": "Be concise.",
  "max_output_tokens": 512,
  "store": false
}'

Leia o texto nos itens de output do tipo message, nas partes de conteúdo output_text. A saída também pode conter chamadas de funções. Confira status e error antes de usar o resultado. usage inclui tokens de entrada/saída/total e detalhes de cache/raciocínio quando informados pelo provedor.

• input aceita uma string ou um array de mensagens/itens. O conteúdo aceita texto e partes input_image com image_url; imagens exigem um modelo com visão. instructions e mensagens developer viram mensagens de sistema.
• max_output_tokens, temperature, top_p e routing usam o pipeline compartilhado. As restrições específicas de cada modelo continuam valendo.
• Envie o histórico completo a cada turno. Omita store ou use false. store: true e qualquer previous_response_id não nulo retornam HTTP 400. Respostas não podem ser recuperadas depois pelo ID.

Raciocínio e saída estruturada

Use reasoning.effort: none, minimal, low, medium, high, xhigh ou max, conforme o modelo. reasoning.summary aceita auto, concise, detailed ou none como preferência de apresentação; não cria raciocínio que o provedor não retornou. Histórico criptografado de raciocínio de outros provedores não é aceito.

text.format suporta text, json_object e json_schema. As opções name, description, schema e strict ficam diretamente no formato. Um schema exige nome e um objeto schema; o provedor valida e aplica seu dialeto. O resultado continua sendo texto JSON dentro de uma parte output_text.

{
  "model": "niuron/auto",
  "input": "Return the capital of Brazil as JSON.",
  "text": {
    "format": {
      "type": "json_schema",
      "name": "capital",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "capital": {
            "type": "string"
          }
        },
        "required": [
          "capital"
        ],
        "additionalProperties": false
      }
    }
  }
}

Esforço de raciocínio e saída estruturada exigem, por enquanto, um adaptador compatível com OpenAI. Os adaptadores Anthropic e Gemini são excluídos dessas requisições porque seus mapeamentos não transportam esses controles. Esforço diferente de none também exige um modelo marcado como capaz de raciocinar. Recursos exclusivos de Responses nativa continuam indisponíveis no transporte upstream por Chat Completions.

Funções e continuação da conversa

Declare funções diretamente no objeto da ferramenta, sem um objeto function aninhado. tool_choice aceita auto, none, required ou um objeto de função com type: function e name: lookup_order. parallel_tool_calls: false exclui adaptadores incapazes de respeitar essa opção.

{
  "model": "niuron/auto",
  "input": "Look up order 42.",
  "tools": [
    {
      "type": "function",
      "name": "lookup_order",
      "description": "Get an order by ID",
      "parameters": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          }
        },
        "required": [
          "id"
        ],
        "additionalProperties": false
      },
      "strict": true
    }
  ]
}

Execute as funções retornadas no seu cliente. Na próxima requisição, mantenha a entrada original, acrescente todos os itens de output retornados e depois um function_call_output para cada chamada. Copie o call_id retornado, não o ID do item; o ID abaixo é ilustrativo. O resultado da ferramenta deve ser uma string: serialize resultados estruturados como texto JSON. Reenvie as ferramentas e instruções relevantes.

{
  "model": "niuron/auto",
  "input": [
    {
      "role": "user",
      "content": "Look up order 42."
    },
    {
      "type": "function_call",
      "call_id": "call_123",
      "name": "lookup_order",
      "arguments": "{\"id\":42}"
    },
    {
      "type": "function_call_output",
      "call_id": "call_123",
      "output": "{\"status\":\"shipped\"}"
    }
  ],
  "tools": [
    {
      "type": "function",
      "name": "lookup_order",
      "description": "Get an order by ID",
      "parameters": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          }
        },
        "required": [
          "id"
        ],
        "additionalProperties": false
      },
      "strict": true
    }
  ]
}

web_search/web_search_preview nativa mantém as restrições existentes por provedor. Citações de busca e itens de saída de ferramentas hospedadas não são reconstruídos; as anotações do texto ficam vazias. Ferramentas gerenciadas pela Niuron têm outro fluxo de execução: veja Ferramentas executadas pelo servidor.

Streaming e eventos finais

Use stream: true e consuma os pares event/data do SSE. Os eventos têm um tipo e sequence_number crescente a partir de zero. O fluxo começa com response.created e response.in_progress, seguido de deltas de texto ou argumentos de funções e eventos done. Os índices dos itens correspondem ao array output final. Aguarde os argumentos completos antes de executar uma função.

• response.completed: conclusão bem-sucedida, incluindo um turno que retorna chamadas de funções.
• response.incomplete: limite de tokens ou filtro de conteúdo. Veja incomplete_details.reason: max_output_tokens ou content_filter.
• response.failed: falha do provedor. Confira error; uma saída parcial não deve ser tratada como chamada de função concluída.

Limitações e cache

Campos e opções não suportados retornam HTTP 400. Background e truncamento automático não estão disponíveis. include aceita reasoning.encrypted_content como projeção opcional; não cria itens de raciocínio que o provedor não retornou. POST /v1/responses/compact gera um resumo cobrado normalmente, criptografado, restrito à organização e válido por 72 horas. Reenvie o item compaction em input. Recuperação por ID, cancelamento e WebSockets não estão disponíveis.

store: false controla a persistência de conversas Responses; o cache de inferência é separado. Envie Cache-Control: no-store ou desative o cache nas configurações da organização para impedir leitura/gravação de cache e shadow routing. As chaves de cache exato incluem esforço e formato de resposta; requisições com esses controles não usam o cache semântico.

API Messages

Use POST /v1/messages para mensagens no formato Anthropic, streaming de texto e chamadas de funções. Autentique com Authorization: Bearer e sua chave Niuron. No SDK, use auth_token e a base URL https://api.niuron.ai, sem acrescentar /v1.

curl https://api.niuron.ai/v1/messages \
  -H "Authorization: Bearer $NIURON_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "niuron/auto",
  "max_tokens": 256,
  "messages": [
    {
      "role": "user",
      "content": "Hello, Niuron!"
    }
  ]
}'

Envie o histórico completo em messages e defina max_tokens. Thinking adaptativo ou com orçamento, esforço e blocos assinados são preservados em modelos Anthropic; esses pedidos usam apenas provedores Anthropic e não usam cache de respostas. Recursos beta adicionais e endpoints de arquivos ou contagem nativa de tokens não fazem parte deste suporte.

Playground de chat

Uma interface de chat no painel que passa pelo exato mesmo pipeline classify-route-execute que a API usa — útil pra testar o roteador, comparar modelos, ou depurar um prompt sem escrever um comando curl. Autenticado pela sua sessão do painel, não por uma chave de API.

• Escolha um modelo (ou deixe em auto) ao iniciar uma nova conversa — fica fixo pra essa conversa assim que a primeira mensagem sai.
• Toda resposta mostra qual modelo e provedor realmente responderam, e pode ser copiada, regenerada (roda de novo só a última resposta com contexto atualizado), ou excluída.
• Conversas persistem por usuário, não compartilhadas com seu time.
• É uso real, não uma sandbox — toda mensagem é uma chamada real de provedor e aparece no histórico de requisições e cobrança igual a uma chamada de API.
• Respostas chegam completas, não em streaming token por token, nesta primeira versão.

Política de roteamento da organização

Owners e admins configuram o roteamento em Configurações → Roteamento. As configurações pertencem à organização ativa, não a um usuário ou chave individual, e valem para todas as chamadas de chat dela.

• As listas aceitam IDs canônicos ou padrões provider/modelo. * corresponde a qualquer trecho, inclusive barras. Exemplo: anthropic/*. Maiúsculas e minúsculas são diferentes. A interface aceita vírgulas ou linhas; a API usa arrays. Limite: 100 padrões por lista, 256 caracteres por padrão.
• Exclusões têm prioridade sobre os permitidos. Listas vazias não restringem. Modelos explícitos, presets, slots gratuitos e fallbacks devem respeitar as listas. Sem modelo compatível, retorna 404 invalid_request_error; o roteador nunca sai das listas silenciosamente.
• Requisições podem substituir cada padrão com routing.cost_tier, routing.allowed_models e routing.excluded_models. Campos omitidos herdam; um array vazio limpa a lista. Ative Exigir regras da organização para que as chamadas não possam alterar a preferência de custo nem as listas de modelos definidas em Configurações. Opções inválidas retornam 400 mesmo com essa opção ativada.
• A faixa de custo continua sendo uma preferência: low, medium, high e xhigh consideram os 20%, 40%, 60% e 80% mais baratos do catálogo ativado; max é irrestrito. Se a faixa não tiver candidato compatível, o roteador relaxa a faixa, nunca as listas de modelos.
• Chamadas com política restritiva de modelos ou objeto routing ignoram cache exato/semântico de respostas e comparações shadow. Isso impede uma resposta antiga em cache de contornar uma política nova.
• Funciona em chat completions, Responses e Anthropic Messages, inclusive streaming, e no playground de chat. A API separada de decisões TypeSafe Jev não participa do roteamento de chat. Atualizações são imediatas no gateway que salvou; outras réplicas atualizam em até 15 segundos.

{
  "model": "niuron/auto",
  "messages": [
    {
      "role": "user",
      "content": "Explain routing in one sentence."
    }
  ],
  "routing": {
    "cost_tier": "low",
    "allowed_models": [
      "anthropic/*",
      "openai/*"
    ],
    "excluded_models": [
      "*preview*"
    ]
  }
}

Perfis de roteamento por aplicação

Crie um perfil em Configurações → Perfis de roteamento e envie seu identificador como modelo. Perfis pertencem à organização e definem prioridades, listas de modelos e requisitos de capacidades. O Niuron continua escolhendo o modelo para cada prompt.

{
  "model": "niuron/profile/support",
  "messages": [
    {
      "role": "user",
      "content": "Explain this code."
    }
  ]
}

• Use niuron/profile/support para a versão ativa ou niuron/profile/support@v2 para fixar a versão 2. A resposta informa a versão resolvida em X-Niuron-Profile-Version. Salvar ou restaurar ativa uma nova versão; versões já fixadas não mudam. Funciona em chat completions, Responses, Anthropic Messages e chat, inclusive streaming.
• Restrições de modelos da organização sempre valem. Quando suas regras são obrigatórias, a preferência de custo da organização também tem prioridade. Perfis não aceitam o objeto routing por chamada. Exigir uma capacidade do modelo não define sozinho o formato de saída. Cache de respostas e comparações shadow são ignorados.
• A prévia é uma simulação determinística gratuita e pode diferir da classificação em produção. O teste real no chat consome créditos. A página mostra as últimas 50 versões e custo de inferência, requisições, erros e latência de 30 dias. Owners/admins editam e veem métricas; membros consultam e testam.

Tool calling

Defina funções com tools e controle sua seleção com tool_choice. O Niuron normaliza function calling entre adaptadores de modelos compatíveis: sua aplicação executa a função e devolve o resultado pelo mesmo contrato de API, mesmo quando o modelo selecionado muda. Com model: "auto", o roteador escolhe um modelo compatível a cada requisição. Esta seção trata de funções executadas pela sua aplicação; ferramentas web executadas pelo Niuron e ferramentas nativas dos provedores têm capacidades e restrições próprias.

curl https://api.niuron.ai/v1/chat/completions \
  -H "Authorization: Bearer ar_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Weather in Boston?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "parameters": {"type": "object", "properties": {"city": {"type": "string"}}}
      }
    }],
    "tool_choice": "auto"
  }'

• tool_choice — "auto", "none", "required", ou fixar uma tool específica por nome — é respeitado de forma idêntica seja o modelo vencedor OpenAI, Anthropic ou Gemini. Um tool_choice fixado costumava ser silenciosamente ignorado em alguns providers; agora todo provider força do mesmo jeito.
• O JSON Schema da sua tool (parameters) viaja pra todo provider quase byte a byte — incluindo additionalProperties, $ref, e uniões de múltiplos tipos, que um campo mais antigo e restrito da API do Gemini costumava rejeitar de cara. A niuron manda pelo campo mais abrangente de JSON Schema do próprio Gemini em vez de reescrever seu schema pra caber num mais estreito — não é garantia de que toda keyword de JSON Schema que existe funciona em todo provider.
• /v1/responses aceita ferramentas function do cliente e ferramentas Niuron em requisições separadas. web_search nativa só é repassada a provedores compatíveis; tipos hospedados não suportados, como file_search, retornam erro explícito em vez de serem descartados. Veja Ferramentas web executadas pelo servidor para o ciclo gerenciado pelo Niuron.
• Funciona igual em todo protocolo que esse gateway fala — tools/tool_choice do /v1/chat/completions, o equivalente no formato Anthropic do /v1/messages, e o do /v1/responses — não só no endpoint em formato OpenAI mostrado aqui.

Ferramentas executadas pelo servidor

Deixe o Niuron executar ferramentas e devolver a resposta final do modelo: pesquisar na web, ler URLs públicas, consultar data/hora atual ou delegar uma tarefa isolada de raciocínio. Disponível em Chat Completions, Responses e Anthropic Messages, com permissões por organização, limites e histórico de uso.

Isso é diferente de function calling comum: com type: function, sua aplicação executa a função e devolve o resultado. Nos quatro tipos de ferramenta Niuron abaixo, o Niuron executa a ferramenta. Não execute as funções internas nem implemente um segundo ciclo de ferramentas para elas.

1. Ative as ferramentas na organização

1. Selecione a organização dona da sua chave de API e abra Settings → Ferramentas do servidor. As ferramentas vêm desativadas, inclusive em organizações existentes que ainda não tenham essa configuração.
2. Um dono ou admin habilita cada ferramenta separadamente: leitura de URLs públicas, busca web, data/hora e subagents isolados. Membros podem usar as permitidas, mas não alterar permissões. Habilitar subagent não habilita ferramentas no filho.
3. Defina os domínios permitidos, o máximo de chamadas por requisição (1–8, padrão 4) e o teto das taxas de busca (US$ 0–US$ 0,20 por requisição, padrão US$ 0,04). São configurações da organização, não sobrescritas no corpo da requisição.
4. Use sua chave normal do Niuron como bearer token. Ela precisa pertencer à organização habilitada e ter acesso a um modelo compatível e créditos suficientes para as operações cobradas.

Se a busca estiver indisponível, peça ao operador da plataforma para configurar a integração. Clientes da API não precisam de uma chave Exa separada. A leitura de URLs públicas não exige chave de provedor de busca.

2. Faça uma chamada de API

Defina NIURON_API_KEY no terminal e execute o exemplo. Informe apenas os tipos de ferramenta hospedada em tools: não inclua schemas de funções, credenciais ou parâmetros próprios de consulta/URL nesses objetos. Coloque a tarefa ou URL pública na mensagem do usuário. Os exemplos usam curl -i para exibir os headers de execução.

curl -i https://api.niuron.ai/v1/chat/completions \
  -H "Authorization: Bearer $NIURON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "niuron/auto",
  "messages": [
    {
      "role": "user",
      "content": "Search for the latest PostgreSQL release notes, read the official source and cite its URL."
    }
  ],
  "tools": [
    {
      "type": "niuron:web_search"
    },
    {
      "type": "niuron:web_fetch"
    }
  ]
}'

O Niuron escolhe um modelo capaz de usar ferramentas. O modelo pode pedir uma ou mais chamadas; o Niuron executa as permitidas e devolve os resultados ao modelo até ele responder ou atingir um limite. Habilitar uma ferramenta não garante que ela será chamada. A resposta usa o formato normal do endpoint, não um payload de função interna que sua aplicação precise executar.

curl -i https://api.niuron.ai/v1/responses \
  -H "Authorization: Bearer $NIURON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "niuron/auto",
  "input": "Search for the latest PostgreSQL release notes, read the official source and cite its URL.",
  "tools": [
    {
      "type": "niuron:web_search"
    },
    {
      "type": "niuron:web_fetch"
    }
  ]
}'

curl -i https://api.niuron.ai/v1/messages \
  -H "Authorization: Bearer $NIURON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "niuron/auto",
  "messages": [
    {
      "role": "user",
      "content": "Search for the latest PostgreSQL release notes, read the official source and cite its URL."
    }
  ],
  "tools": [
    {
      "type": "niuron:web_search"
    },
    {
      "type": "niuron:web_fetch"
    }
  ],
  "max_tokens": 1024
}'

curl -i https://api.niuron.ai/v1/chat/completions \
  -H "Authorization: Bearer $NIURON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "niuron/auto",
  "messages": [
    {
      "role": "user",
      "content": "Read https://www.postgresql.org/docs/ and summarize what this documentation covers. Cite the URL."
    }
  ],
  "tools": [
    {
      "type": "niuron:web_fetch"
    }
  ]
}'

Use niuron/auto para seleção automática ou um ID específico de modelo habilitado no catálogo. Escolher um modelo explícito não ignora seus requisitos de suporte a ferramentas nem as restrições da organização. Cada endpoint mantém seu próprio formato de entrada e resposta final.

Data/hora: niuron:datetime

Consulta o relógio atual do servidor sem acessar serviços externos. O modelo pode informar um fuso IANA, como America/Sao_Paulo; o padrão é UTC. Retorna datetime, utc, unix_time, timezone, utc_offset_seconds e weekday para o mesmo instante. Não converte timestamps históricos arbitrários nem aceita o fuso local do servidor, Local. Fusos inválidos ou desconhecidos geram erro de ferramenta. Não há taxa extra, mas as rodadas do modelo principal ainda consomem tokens.

curl -i https://api.niuron.ai/v1/chat/completions \
  -H "Authorization: Bearer $NIURON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "niuron/auto",
  "messages": [
    {
      "role": "user",
      "content": "What is the current date and time in America/Sao_Paulo? Use the datetime tool."
    }
  ],
  "tools": [
    {
      "type": "niuron:datetime"
    }
  ],
  "tool_choice": "required"
}'

Delegação: niuron:subagent

Delega uma tarefa independente de raciocínio, revisão ou resumo a outra chamada de modelo. O modelo informa task com até 8000 bytes; inclua ali o contexto necessário. O Niuron não encaminha automaticamente histórico ou credenciais, mas tudo incluído em task é enviado ao modelo filho. Herda o campo model ou perfil fixado do pai e as restrições de modelos da organização. Com um preset automático, o roteador pode escolher outro modelo elegível para a subtarefa. Cliente e modelo não escolhem um modelo de subagent separado nos argumentos da ferramenta.

O filho não tem ferramentas, acesso à rede, delegações recursivas ou capacidade de realizar ações externas. São no máximo 2 chamadas filhas por requisição raiz, também contadas no limite compartilhado da organização. Cada filho tem até 1024 tokens de saída e 40 segundos dentro do ciclo de dois minutos do pai. Um resultado limitado por tokens vem marcado como truncated. Trate a resposta como auxílio para síntese ou verificação, não como fonte factual validada independentemente.

curl -i https://api.niuron.ai/v1/chat/completions \
  -H "Authorization: Bearer $NIURON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "niuron/auto",
  "messages": [
    {
      "role": "user",
      "content": "Delegate an independent comparison of TTL-based and event-based cache invalidation, then synthesize the trade-offs."
    }
  ],
  "tools": [
    {
      "type": "niuron:subagent"
    }
  ],
  "tool_choice": "required"
}'

Settings tem um teto separado para custo estimado de modelos filhos: padrão US$ 0,05, faixa US$ 0–US$ 0,20 por requisição raiz. Estimativas de roteamento/fallback precisam caber no saldo desse teto antes do envio, e falhas de cobrança bloqueiam a execução. A estimativa máxima do filho ocupa o orçamento até o fim, mesmo se o custo real for menor; zero impede o envio. Isso limita estimativas admitidas, não garante proteção contra relatórios de uso incorretos do provedor. Tokens reais seguem a inferência normal uma única vez; o registro da ferramenta não faz novo débito. BYOK é preservado. Rodadas principais e buscas ficam fora desse teto.

X-Niuron-Subagent-Cost-USD informa o custo do modelo filho separado das buscas. Esse custo já consta no uso da inferência filha, não é taxa adicional; com BYOK, a cobrança do modelo segue sua chave do provedor, sem novo débito de tokens Niuron. O histórico da ferramenta exibe o custo para visibilidade, enquanto o filho é cobrado por seu request_id distinto. Não some esse registro novamente ao uso faturado do filho. O uso final de tokens inclui rodadas bem-sucedidas do pai e dos filhos. O registro da ferramenta não armazena a tarefa ou resposta delegada.

3. Reutilize no perfil ou no chat

Em Settings → Perfis de roteamento, crie um perfil de pesquisa, habilite ferramentas web e, se necessário, restrinja os domínios. Os campos abaixo pertencem à configuração do perfil, não ao nível principal de uma requisição de chat completions.

{
  "server_tools": [
    "niuron:web_search",
    "niuron:web_fetch"
  ],
  "tool_allowed_domains": [
    "postgresql.org"
  ]
}

Após criar um perfil com identificador research e versão 1, use a referência em vez de repetir a lista de ferramentas. A referência abaixo é ilustrativa: crie o perfil na sua organização antes de usá-la.

curl -i https://api.niuron.ai/v1/chat/completions \
  -H "Authorization: Bearer $NIURON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "niuron/profile/research@v1",
  "messages": [
    {
      "role": "user",
      "content": "Search for the latest PostgreSQL release notes, read the official source and cite its URL."
    }
  ]
}'

• Use niuron/profile/research para acompanhar a versão ativa ou niuron/profile/research@v1 para fixar uma configuração imutável. Alterar ferramentas e salvar cria uma nova versão. A simulação determinística do perfil não executa ferramentas.
• As permissões da organização sempre valem, inclusive em versões fixadas. Os domínios do perfil fazem interseção com os da organização: um perfil não libera um domínio proibido pela organização. Revogar uma ferramenta na organização bloqueia novas requisições que dependam dela.
• A lista server_tools do perfil ativa ferramentas automaticamente. É uma lista padrão, não uma lista independente de bloqueio: ferramentas Niuron explícitas na requisição podem acrescentar outras permitidas pela organização. Não combine padrões do perfil com funções do cliente ou ferramentas nativas do provedor.

No chat, abra o menu Ferramentas e escolha HTTP público, Busca na web, Data e hora atual ou Subagent isolado. Opções desabilitadas indicam indisponibilidade pela configuração da organização ou da integração de busca. Escolher um perfil com ferramentas ativa seus padrões mesmo com as opções manuais desligadas. As continuações e chamadas de modelos filhos também consomem créditos no chat.

Domínios, limites e streaming

• Domínios permitidos são nomes DNS como postgresql.org, sem protocolo, caminho, porta, IP ou curinga. Separe por vírgulas ou linhas em Settings; subdomínios estão incluídos. Uma lista vazia permite todos os domínios públicos, não redes privadas. São aceitos até 50 domínios.
• Por exemplo, organização com postgresql.org e perfil com www.postgresql.org permite esse host e seus subdomínios, não sites externos a ele. Listas sem interseção são rejeitadas antes de executar o modelo. Resultados de busca são filtrados pela política efetiva de domínios.
• Leituras aceitam somente HTTP/HTTPS em portas padrão, GET/HEAD e conteúdo texto/JSON/XML, até 16 KiB. Textos maiores são truncados. Credenciais na URL, redes privadas/reservadas e redirecionamentos são bloqueados; informe a URL final permitida em vez de depender de redirect. POST e outros métodos que alteram estado não são aceitos.
• Cada leitura de URL tem limite de 8 segundos, cada busca de 12 segundos e o ciclo de ferramentas de 2 minutos. Continuam valendo os prazos do modelo/provedor. Chamadas inválidas ou bloqueadas também consomem o contador da requisição. Ao esgotá-lo, o Niuron pede ao modelo para concluir com o que já obteve; novas chamadas de ferramenta podem gerar erro.
• Com stream: true, esta versão acumula as rodadas e envia apenas a resposta final por SSE. Não transmite tokens durante as consultas nem eventos intermediários de ferramentas para o cliente executar. Ajuste os timeouts do cliente e do proxy para comportar a fase de consultas.
• Não misture ferramentas Niuron com type: function ou ferramentas nativas como web_search na mesma requisição: essa mistura é rejeitada. Busca nativa do provedor não é um apelido da busca Niuron. Tipos hospedados não suportados retornam erro explícito, sem descarte silencioso.
• Requisições com ferramentas do servidor não leem nem escrevem no cache de respostas, inclusive nas rodadas intermediárias. Repetir uma requisição pode realizar novas buscas, chamadas de modelo e cobranças.

Entenda a cobrança antes de habilitar

• Cada rodada do modelo consome tokens, incluindo a decisão inicial de ferramentas e as continuações. Uma pesquisa pode custar mais do que uma completion comum. Tokens já consumidos continuam sujeitos à cobrança mesmo se uma etapa posterior falhar.
• Ler URLs públicas não tem taxa adicional de ferramenta. Porém, o texto externo devolvido ao modelo acrescenta tokens de entrada, e o resumo do modelo acrescenta tokens de saída.
• A busca é cobrada pelo custo informado pelo provedor. Uma busca pode não trazer resultados úteis e ainda informar custo. A taxa é separada dos tokens do modelo; não é um preço fixo por mensagem de chat.
• Antes de pesquisar, o Niuron verifica a cobrança e reserva uma parcela conservadora de US$ 0,02 do limite. O teto da organização limita essas parcelas, não o custo total: um teto de US$ 0,04 permite no máximo duas buscas enviadas ao provedor, mesmo que a primeira custe menos. A liquidação normal libera o valor reservado não utilizado. Um teto abaixo de US$ 0,02 não deixa parcela para busca; o modelo pode explicar a limitação sem pesquisar. O teto não inclui custos do LLM.
• BYOK se aplica ao modelo de linguagem, não à integração de busca da plataforma. A busca continua consumindo créditos Niuron quando o modelo usa sua própria chave de provedor. O comportamento de cobrança BYOK do modelo não muda.
• Falhas no serviço de cobrança ou no registro financeiro impedem o envio de buscas pagas. Custos de busca ausentes ou ambíguos não são estimados e cobrados do cliente. Se o custo informado exceder o teto reservado, a taxa do cliente fica limitada à reserva e o resultado é rejeitado. Uma resposta final com erro não significa automaticamente custo zero.

Exemplo ilustrativo, não uma cotação: duas rodadas do modelo somando US$ 0,004 e uma busca que informe US$ 0,012 consomem US$ 0,016 no total. X-Niuron-Tool-Cost-USD informa apenas 0.012000, não os US$ 0,016 combinados. A reserva de US$ 0,02 não é uma taxa extra somada ao custo informado da busca.

Confira uso e histórico de execução

X-Niuron-Request-ID: chatcmpl-example
X-Niuron-Tool-Calls: 2
X-Niuron-Tool-Cost-USD: 0.012000

• X-Niuron-Request-ID identifica a requisição raiz da API. Guarde esse valor ao acionar o suporte ou investigar uma falha.
• X-Niuron-Tool-Calls conta tentativas de chamadas pelo modelo, inclusive inválidas ou bloqueadas. Pode ser zero quando o modelo responde sem usar ferramentas.
• X-Niuron-Tool-Cost-USD informa taxas de busca da requisição, sem os tokens do modelo. Taxa de ferramenta zero não significa custo total zero.
• O uso de tokens da resposta final soma as rodadas bem-sucedidas do modelo, não apenas a última resposta. Rodadas de modelo e ferramentas enviadas têm IDs de cobrança distintos e aparecem como entradas separadas de uso. A soma delas, não apenas o header da ferramenta, representa o consumo total.
• Settings → Ferramentas do servidor → Carregar últimas 100 execuções mostra chamadas enviadas, status, host, duração, custo e ID da requisição raiz. Os dados são isolados por organização. Chamadas bloqueadas antes do envio podem entrar no contador do header sem aparecer como execuções enviadas. Um registro parado em started pode indicar interrupção ou resultado ambíguo: consulte o suporte antes de repetir uma chamada cara.
• O registro de execução de ferramentas não armazena consultas de busca, caminhos/parâmetros completos das URLs, conteúdo externo, credenciais, prompts ou respostas geradas. Isso vale para esse registro, não é uma política global de retenção zero: o chat mantém seu histórico normal, e consultas/URLs e resultados são processados pelos provedores externos e pelo modelo envolvidos.

Diagnóstico e retentativas seguras

Nem toda consulta malsucedida vira erro HTTP. Erro no provedor de busca, URL bloqueada ou orçamento de busca esgotado pode chegar ao modelo como resultado da ferramenta; ele ainda pode produzir uma resposta HTTP 200 explicando as limitações. HTTP 200 não comprova sucesso de todas as consultas nem ausência de consumo. Considere as fontes e ressalvas da resposta final.

O Niuron não repete buscas pagas automaticamente. Retentativas da sua aplicação são novas requisições e podem repetir operações e cobranças. Não presuma proteção contra reexecução ou idempotência ao repetir um POST. Em timeout ambíguo ou registro started, consulte o histórico ou suporte primeiro.

Use informações públicas, não segredos

Nunca inclua senhas, chaves de API ou dados privados da conversa nas instruções de pesquisa ou URLs. Conteúdo externo é dado não confiável, não fonte de instruções. O Niuron orienta o modelo a citar fontes e ignorar instruções externas, mas isso não é defesa absoluta contra prompt injection ou respostas incorretas. Restrinja domínios em fluxos sensíveis, confira as fontes e use funções do seu próprio backend autenticado para sistemas privados.

TypeSafe Jev: API de decisões

Use POST /v1/systemone para classificar mensagens, escolher uma categoria ou pontuar um conteúdo. Jev recebe um state (texto, objeto ou array) e um mapa de questions, e devolve decisões estruturadas — não respostas de chat nem texto livre.

Crie sua chave em /app/api-keys e defina NIURON_API_KEY no ambiente do seu backend. O header Authorization: Bearer recebe essa chave da niuron, não uma chave TypeSafe. Adicione créditos à sua conta para executar chamadas pagas.

curl https://api.niuron.ai/v1/systemone \
  -H "Authorization: Bearer $NIURON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "jev-latest",
  "state": "My payment failed and I need this resolved today.",
  "questions": {
    "urgent": {
      "type": "noul",
      "instructions": "Does this message express urgency?"
    },
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this?",
      "criteria": {
        "billing": "Payments and refunds",
        "technical": "Bugs and integrations"
      }
    },
    "priority": {
      "type": "score",
      "instructions": "Rate the priority of this request.",
      "criteria": [
        "Low",
        "Medium",
        "High"
      ]
    }
  }
}'

• noul: pergunta de sim/não. Retorna a probabilidade de sim, entre 0 e 1; não é um booleano. Seu código define o limiar para agir.
• choice: escolhe uma das opções em criteria. Retorna choice, a distribuição probabilities e confidence.
• score: avalia níveis ordenados em criteria. Retorna score, legend, probabilities e confidence. O score pode ser fracionário; os níveis começam em zero.

Como ler a resposta

Cada chave de answers corresponde à chave que você enviou em questions. model informa a versão que executou a avaliação; usage informa os tokens consumidos. Os valores e o uso abaixo são ilustrativos, não uma previsão para sua chamada. Use a confiança/probabilidade para decidir quando agir ou pedir revisão; uma decisão estruturada também pode estar errada.

{
  "model": "jev-1.13.0",
  "answers": {
    "urgent": {
      "type": "noul",
      "noul": 0.95
    },
    "department": {
      "type": "choice",
      "choice": "billing",
      "probabilities": {
        "billing": 0.9,
        "technical": 0.1
      },
      "confidence": 0.8
    },
    "priority": {
      "type": "score",
      "score": 1.8,
      "legend": {
        "0": "Low",
        "1": "Medium",
        "2": "High"
      },
      "probabilities": {
        "0": 0,
        "1": 0.2,
        "2": 0.8
      },
      "confidence": 0.7
    }
  },
  "usage": {
    "input_tokens": 512,
    "output_tokens": 80
  }
}

Modelos disponíveis

Consulte GET /v1/systemone/models com sua chave niuron para listar modelos de decisão e preços. Inicialmente, jev-latest, jev-preview e jev-1.13.0 apontam para jev-1.13.0 na niuron; esses aliases não acompanham automaticamente alterações no TypeSafe. GET /v1/models continua listando modelos de chat, não Jev.

curl https://api.niuron.ai/v1/systemone/models \
  -H "Authorization: Bearer $NIURON_API_KEY"

Cobrança, BYOK e limites

• Preço inicial: US$ 0,042 por milhão de tokens de entrada; tokens de saída gratuitos. O débito usa o consumo efetivo retornado. Durante a execução, pode haver uma reserva temporária de até US$ 0,002688, correspondente ao limite de 64 mil tokens; a diferença é liberada na liquidação. Confira os preços atuais na listagem de modelos.
• Para usar sua própria conta TypeSafe, adicione a credencial ao provider typesafe na área de provedores do dashboard. Continue autenticando a chamada com sua chave niuron. A política BYOK da sua conta se aplica; não envie a chave TypeSafe no corpo da requisição.
• Até 1 MiB por requisição e 1–256 perguntas. Choice aceita 2–255 opções; Score, 2–10 níveis. instructions aceita texto, objeto ou array.
• Limites do modelo: 64 mil tokens no estado mais todas as perguntas, e 32 mil para o estado mais a maior pergunta. O provider valida os limites de tokens; uma requisição pode estar abaixo de 1 MiB e ainda excedê-los.
• Não use /v1/chat/completions, /v1/responses ou /v1/messages para Jev. Não há stream, mensagens de chat, imagens, tools nem roteamento auto nessa API.
• Faça as chamadas no backend. Nunca exponha sua chave niuron em JavaScript público, apps distribuídos ou repositórios.

Erros e próximos passos

Erros retornam error.type e error.message. Guarde o header X-Niuron-Request-ID ao solicitar suporte. Se financial_storage_unavailable vier com a mensagem de que o resultado precisa de conciliação, não repita automaticamente: fale com o suporte usando esse ID. Falhas na conta TypeSafe da plataforma são tratadas como indisponibilidade; problemas na conta BYOK são identificados como seus.

Agentes de código e IDEs

O Claude Code usa o formato Messages da Anthropic e o Codex CLI usa Responses. A Niuron oferece POST /v1/messages e POST /v1/responses pelo pipeline compartilhado de chat. O endpoint Responses suporta o subconjunto stateless documentado acima; recursos exclusivos da API nativa e opções não suportadas são rejeitados. As outras integrações abaixo usam /v1/chat/completions com a URL base https://api.niuron.ai/v1.

export ANTHROPIC_BASE_URL=https://api.niuron.ai
export ANTHROPIC_AUTH_TOKEN=ar_live_...
export ANTHROPIC_MODEL=niuron/auto

model = "niuron/auto"
model_provider = "niuron"

[model_providers.niuron]
name = "niuron"
base_url = "https://api.niuron.ai/v1"
env_key = "NIURON_API_KEY"
wire_api = "responses"

export COPILOT_PROVIDER_BASE_URL=https://api.niuron.ai/v1
export COPILOT_PROVIDER_API_KEY=ar_live_...
export COPILOT_MODEL=niuron/auto
copilot

Base URL:  https://api.niuron.ai/v1
API Key:   ar_live_...
(click Verify)

Base URL:  https://api.niuron.ai/v1
API Key:   ar_live_...
Model ID:  niuron/code

Base URL:  https://api.niuron.ai/v1
API Key:   ar_live_...
Model:     niuron/code

Base URL:  https://api.niuron.ai/v1
API Key:   ar_live_...

models:
  - name: niuron
    provider: openai
    model: niuron/code
    apiBase: https://api.niuron.ai/v1
    apiKey: ar_live_...

{
  "language_models": {
    "openai_compatible": {
      "niuron": {
        "api_url": "https://api.niuron.ai/v1",
        "available_models": [
          { "name": "niuron/auto", "display_name": "niuron", "max_tokens": 128000 }
        ]
      }
    }
  }
}

Settings -> Tools -> AI Assistant -> Providers & API keys
Provider:   OpenAI-compatible
Base URL:   https://api.niuron.ai/v1
API Key:    ar_live_...
(Test Connection)

export OPENAI_API_BASE=https://api.niuron.ai/v1
export OPENAI_API_KEY=ar_live_...
aider --model openai/niuron/code

OPENAI_BASE_URL=https://api.niuron.ai/v1
OPENAI_API_KEY=ar_live_...

Cache

Duas camadas independentes, ambas aplicadas antes de qualquer provedor ser chamado:

O resultado do cache de cada requisição (hit ou miss, e qual camada) fica visível em cada linha no histórico de requisições, e agregado como taxa de acerto na visão geral.

Observabilidade

Gerenciamento de conta