Documentação

Pi

Pi — o agente de programação para terminal da Earendil, não o chatbot da Inflection nem a moeda — recebe um provedor personalizado em um único bloco de models.json: baseUrl, api, uma chave e os IDs de modelo desejados. Quatro campos e ele já se comunica com Claude e GPT usando uma única chave.

Um bloco de provedor personalizado em ~/.pi/agent/models.json — baseUrl, api e os IDs dos modelos — coloca o agente de programação de terminal Pi da Earendil em Claude e GPT por meio de uma única chave.

~/.pi/agent/models.json

{
  "providers": {
    "kunavo": {
      "baseUrl": "https://api.kunavo.com/v1",
      "api": "openai-completions",
      "apiKey": "$KUNAVO_API_KEY",
      "models": [
        {
          "id": "claude-sonnet-5",
          "name": "Claude Sonnet 5",
          "reasoning": true,
          "input": ["text", "image"],
          "contextWindow": 1000000,
          "maxTokens": 128000
        },
        {
          "id": "claude-haiku-4-5",
          "name": "Claude Haiku 4.5",
          "input": ["text", "image"],
          "contextWindow": 200000,
          "maxTokens": 64000
        }
      ]
    }
  }
}

Mantenha o /v1 em um provedor openai-completions. O exemplo de endpoint compatível na página de modelos do Pi associa esse valor a http://localhost:11434/v1, e, antes da reescrita da documentação em 22 de setembro, os exemplos de OpenRouter, Vercel AI Gateway e llama.cpp usavam o mesmo caminho de versão. Nenhuma frase declara a regra explicitamente, então são os exemplos que a esclarecem. Uma URL base sem o sufixo retorna 404, não um erro de autenticação.

O valor de cost de um modelo personalizado começa com todos os zeros — esse padrão está no código-fonte do Pi (v0.99.2), mas a documentação não o explica mais. Por isso, o provedor que você acabou de adicionar exibe $0 no rodapé e em /session até que você informe as tarifas manualmente. Os dois padrões silenciosos seguintes causam problemas ainda maiores: contextWindow usa 128000 como valor alternativo e maxTokens usa 16384, então um modelo deixado sem esses valores terá o contexto compactado e truncado muito antes do limite que realmente suporta. O bloco acima define ambos com base no catálogo; faça o mesmo para qualquer ID que adicionar da tabela abaixo.

Onde o Pi procura a chave, na ordem em que faz isso. A página de modelos do Pi diz que, quando várias fontes estão configuradas, ele usa “primeiro um --api-key em tempo de execução; depois, uma credencial auth.json armazenada; um apiKey de models.json; e, por fim, as variáveis de ambiente do provedor”. Assim, uma chave antiga salva por /login prevalece sobre a do arquivo, o que costuma explicar por que um bloco editado recentemente ainda autentica como outra conta. A mesma página acrescenta que os modelos personalizados “podem ser carregados de models.json, mas permanecem indisponíveis em /model até que o Pi consiga resolver as credenciais” — se um modelo não aparecer no seletor, o problema está nas credenciais, não na sintaxe.

Este bloco foi extraído da documentação do próprio Pi na data indicada abaixo; o que essa documentação deixou de informar em 22 de setembro — os nomes dos campos, os padrões de modelos personalizados e os valores de api — foi obtido do código-fonte do Pi na v0.99.2, no mesmo dia. O Kunavo não executou o Pi contra seu endpoint: nenhuma sessão, turno transmitido em streaming, interação de ida e volta com ferramentas ou verificação de qual modelo recebeu uma solicitação. Uma página de configuração publicada é uma referência de configuração, não um teste de compatibilidade, e nada aqui deve ser interpretado como tal. O curl abaixo é a parte que você pode resolver em dez segundos; o comportamento do cliente depende de você e do Pi.

Ainda não tem uma chave? Crie uma conta na Kunavo, gere uma chave (ela começa com sk-kn-) e adicione crédito a partir de $10 — as chamadas são pagas com esse saldo, e chamadas malsucedidas não são cobradas. O painel então abre na configuração de Pi.

Passo a passo

Crie uma chave em /app/keys e copie-a — ela é exibida uma única vez.
Defina-o no ambiente como KUNAVO_API_KEY. O Pi resolve "$NAME" ou "${NAME}" no campo apiKey, além de aceitar um valor literal ou um !command no início. Use a forma entre chaves quando houver texto literal após o nome da variável.
Crie ou edite ~/.pi/agent/models.json e cole o bloco acima. Um provedor que não seja integrado precisa de baseUrl e de um valor para api no nível do provedor ou do modelo — o código-fonte do Pi se recusa a carregar o modelo sem eles — e todo o restante é opcional. Abrir /model recarrega o arquivo.
Inicie pi, execute /model e escolha um dos IDs declarados. Se eles não aparecerem na lista, confira a chave antes do JSON — veja a observação sobre a ordem de resolução acima.
Peça uma tarefa que leia e edite um arquivo real. O Pi depende de chamadas a ferramentas para quase tudo o que faz, então uma primeira execução que mexa no sistema de arquivos informa muito mais do que uma saudação — e é essa execução que revelaria uma incompatibilidade de streaming ou de esquema de ferramentas, exatamente o tipo de coisa que o Kunavo não testou para você.

Verificado em Documentação do Pi: Escolher um modelo em 1 de outubro de 2026. As configurações de terceiros podem mudar; se o nome de um campo aqui já não corresponder ao que você vê, aquela página é a autoridade, não esta.

Esta é a versão resumida. O guia completo — escolha do modelo, custo de uma sessão real e modos de falha — está em quanto realmente custa executar o Pi, rota por rota.

Verifique antes de depurar o cliente

Uma solicitação determina se a falha está no endpoint, na chave ou no arquivo de configuração. Se isto retornar JSON, a mesma URL base e a mesma chave funcionarão em Pi.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

Qual ID de modelo inserir no campo

Todo modelo de texto pode ser acessado como um ID de modelo — a lista atual está em GET /v1/models, e o catálogo com preços está na página de modelos. As tarifas são em USD por 1 milhão de tokens, entrada / saída.

ID do modelo	Entrada / saída da Kunavo	Onde se encaixa em Pi
`claude-sonnet-5`	$1.40 / $7.00	o modelo de trabalho padrão para sessões que editam arquivos
`claude-opus-5`	$3.50 / $17.50	planejamento de uma mudança em que errar sairia caro
`claude-haiku-4-5`	$0.70 / $3.50	interações baratas — triagem, resumos e o ciclo que roda o dia inteiro
`gpt-5-6-sol`	$2.00 / $12.00	uma segunda opinião de outra família, com a mesma chave e o mesmo baseUrl

A cobrança é por token, usando um saldo pré-pago e sem tarifa mensal — consulte billing. Em contextos repetidos — que representam a maior parte do que um editor ou cliente de chat envia — o cache de prompt altera a conta mais do que a escolha do modelo.

A outra opção: `anthropic-messages`

Até a atualização da documentação em 22 de setembro de 2026, o Pi documentava quatro valores para api de um provedor personalizado: openai-completions, openai-responses, anthropic-messages e google-generative-ai. A página atualizada de modelos não lista nenhum: mostra openai-completions em um exemplo e descreve o caso como “Um endpoint compatível com OpenAI, Anthropic ou Google”. No código-fonte da v0.99.2, o Pi tipa o campo como uma string livre e o direciona para qualquer uma das dez implementações integradas correspondentes — as quatro anteriores, mais openai-codex-responses, azure-openai-responses, google-vertex, mistral-conversations, bedrock-converse-stream e pi-messages. Apenas as quatro chegaram a ser documentadas para um provedor personalizado, e nenhuma das outras seis foi testada aqui; esta página não afirma que qualquer uma delas funcione com um endpoint de terceiros.

anthropic-messages é um dos quatro valores documentados, e o Kunavo atende tanto à interface Anthropic Messages quanto à interface compatível com OpenAI. Portanto, é possível expressar essa rota. O que esta página não fará é incluir uma URL base para ela em um bloco pronto para colar: a documentação do Pi nunca definiu esse campo para esta api. Até 22 de setembro, ela o mostrava de duas formas — https://proxy.example.com/v1 em um exemplo e um https://proxy.example.com sem prefixo em outro — e a atualização da documentação removeu ambos, em vez de escolher um. Se você seguir essa rota, experimente uma das formas; se a primeira chamada retornar 404 em vez de 401, é essa linha que você deve alterar.

Vale a pena conhecer três campos do esquema de compat do Pi para esta api antes de chegar lá (código-fonte, v0.99.2). Também vale citar primeiro a única regra da documentação que se aplica aos três: as configurações de compatibilidade “devem descrever diferenças verificadas no comportamento de solicitação ou resposta do endpoint. Não as habilite apenas porque um endpoint anuncia compatibilidade com OpenAI ou Anthropic”.

compat.supportsEagerToolInputStreaming — para um backend que rejeita o envio antecipado da entrada de cada ferramenta.
compat.supportsStrictTools — indica se o endpoint aceita definições de ferramentas com esquema JSON estrito; um modelo personalizado não herda o que um modelo Anthropic integrado declara.
compat.supportsMidConvoEffort — altera o nível de raciocínio no meio da conversa. Saber se este endpoint atende a esse requisito é uma questão de execução, e o Kunavo não verificou isso executando nada.

O bloco openai-completions no início desta página evita os três, e essa é a razão honesta para começar por ele, não uma afirmação de que tenha um desempenho melhor.

Perguntas frequentes

Como direciono o agente de programação Pi para um provedor de API personalizado?

Adicione um bloco de provedor a ~/.pi/agent/models.json. A página de modelos do Pi diz para usar models.json “quando um endpoint oferece uma API que o Pi já aceita”, e o esquema (código-fonte, v0.99.2) aceita baseUrl, apiKey, api, headers, authHeader, models e modelOverrides no nível do provedor. Um provedor que não seja integrado precisa de baseUrl e de um valor para api no nível do provedor ou do modelo. O esquema tipa api como uma string livre, não como uma lista: até a atualização da documentação em 22 de setembro de 2026, o Pi documentava quatro valores para um provedor personalizado — openai-completions, openai-responses, anthropic-messages e google-generative-ai — e, na v0.99.2, seu código-fonte direciona o campo para qualquer uma das dez implementações integradas; as outras seis nunca foram documentadas para esse uso nem testadas aqui. Para um endpoint compatível com OpenAI, openai-completions é o valor que a documentação atualizada ainda mostra. Cada entrada em models precisa de pelo menos um id, que é enviado diretamente ao endpoint; portanto, o mesmo formato atende a um gateway, um servidor local Ollama ou vLLM e qualquer outro host compatível.

De onde o agente de programação Pi obtém sua chave de API?

De um de quatro lugares, cuja ordem é publicada na página de modelos do Pi: primeiro, --api-key em tempo de execução; depois, uma credencial salva em auth.json; em seguida, apiKey de models.json; por fim, as variáveis de ambiente do provedor. Portanto, uma chave salva anteriormente com /login tem precedência sobre a que você acabou de editar em models.json. O próprio campo apiKey aceita interpolação de variáveis de ambiente — "$NAME" ou "${NAME}" —, um valor literal ou a saída de um comando do shell com "!" no início, para que o segredo não precise ficar no arquivo. Sem credenciais utilizáveis, a documentação diz que os modelos personalizados são carregados de models.json, mas permanecem indisponíveis em /model.

O baseUrl do Pi precisa terminar em /v1?

Para um provedor openai-completions, sim. A documentação do Pi não declara a regra em uma frase, mas o exemplo de endpoint compatível usa http://localhost:11434/v1 para o Ollama; antes da atualização da documentação em 22 de setembro de 2026, os exemplos de OpenRouter, Vercel AI Gateway e llama.cpp também incluíam o mesmo caminho de versão. Portanto, para um endpoint compatível com OpenAI, o valor é a raiz /v1, por exemplo, https://api.kunavo.com/v1. O caso anthropic-messages continua sem definição clara: a documentação antiga mostrava o valor com e sem /v1, e a atualização removeu ambos os exemplos sem escolher.

Por que meu provedor personalizado do Pi mostra US$ 0 no rodapé?

Porque, por padrão, o objeto de custo de um modelo personalizado no Pi é todo preenchido com zeros (código-fonte, v0.99.2), e o rodapé informa o que está no catálogo, não o que o endpoint cobra. Nada é gratuito; o número simplesmente não tem uma fonte até você preencher as tarifas por milhão de tokens de entrada, saída, cacheRead e cacheWrite, além de quaisquer faixas de preço, usando a lista de preços do seu provedor. Dois outros valores padrão próximos merecem a mesma atenção: contextWindow assume 128000 e maxTokens, 16384. Assim, um modelo com uma janela maior é compactado antes da hora e suas respostas são interrompidas, a menos que ambos sejam definidos explicitamente.

O Kunavo testou o agente de programação Pi?

Não. A configuração desta página foi consultada na documentação do próprio Pi e, nos casos em que a atualização de 22 de setembro removeu um detalhe, no código-fonte publicado do Pi, na data indicada. Porém, este cliente não foi usado para executar nenhuma sessão, turno transmitido em streaming, interação de ida e volta com ferramentas ou verificação de roteamento de modelos contra este endpoint — e o mesmo vale para todos os clientes desta seção. Use o bloco de configuração como referência do que o esquema do Pi aceita, verifique o endpoint e a chave com o comando curl acima e mantenha uma rota funcional disponível enquanto você experimenta.