Documentação

Dify

O Dify acessa um endpoint externo por meio de um plug-in — OpenAI-API-compatible — e de um campo obrigatório, API Base URL. Preencha-o, e todos os nós de LLM nos seus fluxos de trabalho poderão acessar IDs Claude e GPT usando uma única chave.

Um único campo obrigatório — API Base URL, no formulário Add Model do plugin compatível com OpenAI-API — aponta todos os nós LLM de um workspace Dify para a Kunavo.

Model Provider → OpenAI-API-compatible → Add Model

# Integrations → Model Provider → OpenAI-API-compatible → Add Model
Type                          LLM
Model Name                    claude-sonnet-5
Model display name            Kunavo · Claude Sonnet 5
API Key                       sk-kn-...
API Base URL                  https://api.kunavo.com/v1
model name for API endpoint   (leave blank — Model Name is already the id)
Completion mode               Chat
Model context size            1000000
Upper bound for max tokens    (your own ceiling for one reply)
Function Call Type            Tool Call     # defaults to no_call
Vision Support                Support       # only if you will send images
Structured Output             Support       # defaults to not supported

# Model context size is per model, not per endpoint: 1000000 is
# claude-sonnet-5's. The table below carries the rest.

API Base URL mantém o /v1. O plug-in declara endpoint_url com o rótulo API Base URL, define-o como o único campo obrigatório além do nome do modelo e usa o texto de exemplo “Base URL, por exemplo, https://api.openai.com/v1” — é essa indicação que esclarece como preencher o formulário. O próprio README do plug-in explica a exceção, sem contradizê-la: para tipos de modelo que não sejam LLM, o plug-in “acrescenta internamente a versão da API”, então esses tipos recebem a origem sem caminho para evitar um /v1/v1 duplicado. Nenhum modelo da Kunavo pertence a esses tipos, então só é necessário usar o formulário /v1.

Três opções vêm desativadas por padrão e costumam causar problemas. Function Call Type tem como padrão no_call, e Structured Output e Vision Support ficam como não compatíveis. Um modelo adicionado com os valores padrão responde perfeitamente em um nó de chat simples e depois falha em um nó Agent ou em um fluxo de trabalho que usa ferramentas — o que parece ser uma falha do endpoint, mas não é. Defina essas opções ao adicionar o modelo, antes de depurar qualquer outra coisa.

A Kunavo não oferece modelos de embeddings, de conversão de texto em fala nem de conversão de fala em texto, e também não oferece reranking — portanto, esta entrada de provedor cobre apenas o espaço de LLM do Dify. Uma base de conhecimento indexada no modo High Quality, uma URL de Rerank Endpoint ou um nó de voz mantém o provedor que já usa; apontar um nó LLM para cá não redireciona essas chamadas.

Esta configuração foi consultada na listagem do próprio plugin do Dify e no esquema do provedor na data abaixo. A Kunavo não executou um workspace do Dify contra seu endpoint — nenhum modelo foi adicionado a um workspace ativo, nenhum fluxo de trabalho foi executado e nenhuma chamada de ferramenta foi testada com streaming de ponta a ponta. Uma página de configuração publicada não é um teste. O curl abaixo é a parte que você pode confirmar em dez segundos; todo o resto depende de você e do Dify.

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

Passo a passo

Crie uma chave em /app/keys e copie-a — ela é exibida uma única vez.
No Dify, abra Integrations → Model Provider, acesse Install model providers (ou o Marketplace) e instale OpenAI-API-compatible, publicado por langgenius. A documentação do Dify informa que apenas o proprietário do workspace e os administradores podem gerenciar provedores.
Clique em Add Model no cartão desse provedor. O plugin não oferece modelos predefinidos — é um provedor customizable-model —, portanto cada ID que você quiser precisa de uma entrada própria.
Preencha o formulário como acima. Type = LLM, Model Name = o ID da Kunavo exatamente como consta, API Key = sua chave sk-kn-, API Base URL = https://api.kunavo.com/v1, Completion mode = Chat e Model context size conforme a tabela abaixo. Em seguida, defina Function Call Type, além de Structured Output e Vision Support, se precisar. Salve.
Abra um fluxo de trabalho e selecione o modelo no nó que deve usá-lo — o Dify atribui modelos por nó, não por aplicativo, então um classificador e um redator final podem usar IDs e preços diferentes. Aplicativos e nós sem modelo selecionado usam Default Models → System Reasoning Model como alternativa.
Execute um fluxo de trabalho de escopo limitado e confira a cobrança na sua conta Kunavo, não no Dify — veja a observação sobre a exibição de custos abaixo.

Verificado em Página do plugin OpenAI-API-compatible do Dify em 21 de setembro 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 o guia de custos do Dify.

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

# 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 Dify
`claude-sonnet-5`	$1.40 / $7.00	o modelo de trabalho para nós de redação e agente — tamanho do contexto: 1000000
`claude-opus-5`	$3.50 / $17.50	o nó cuja saída será lida por uma pessoa, ou um plano em que um erro custa caro — 1000000
`claude-haiku-4-5`	$0.70 / $3.50	nós de classificação, roteamento e extração, onde o volume de chamadas realmente se concentra — 200000
`gpt-5-6-sol`	$2.00 / $12.00	uma segunda família usando a mesma chave, em sua própria entrada de modelo — 1050000
`gpt-5-6-terra`	$0.70 / $4.20	nós para documentos longos — 1050000

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.

Duas coisas diferentes são chamadas de “API do Dify”

Esta página trata de uma delas, mas os resultados de busca as misturam o tempo todo.

Adicionar um modelo ao Dify — é isso que o bloco de configuração acima faz. O Dify é o cliente, a Kunavo é o endpoint e a credencial que você cola é uma chave sk-kn-. Assim, todos os nós de LLM em todos os aplicativos desse workspace podem usar os IDs adicionados.
Chamar um aplicativo do Dify a partir do seu próprio código — a Service API que o Dify disponibiliza para um aplicativo publicado, com uma chave app- própria, emitida pelo Dify. Essa chave é do Dify, não nossa, e não é possível apontá-la para outro lugar. A Kunavo não participa desse fluxo.

Os dois fluxos podem ocorrer ao mesmo tempo no mesmo aplicativo, e normalmente ocorrem: seu backend chama o aplicativo do Dify com uma chave do Dify, e os nós do aplicativo chamam a Kunavo com uma chave da Kunavo. São duas chaves, duas cobranças e dois lugares para investigar quando algo retorna 401.

Por que o Dify não exibe custos para o modelo que você adicionou

Os arquivos de modelo predefinidos oficiais do Dify incluem um bloco de preços — tarifas de entrada e saída e uma unidade por token —, e o Dify multiplica suas contagens de tokens por esses valores para exibir um valor no registro. O esquema do provedor OpenAI-API-compatible não declara nenhum campo de preço, unidade ou moeda, conforme verificado na data acima. Portanto, para um modelo adicionado por meio desse plugin, o Dify não tem uma tarifa para multiplicar; a coluna de valores não representa um desconto que você encontrou nem um erro que você causou: é um campo que não existe. Consulte o valor real no uso registrado pela Kunavo e interprete as contagens do Dify como contagens de tokens.

Vale a pena deixar uma opção relacionada como está: Include Usage in Stream vem ativada por padrão e solicita ao endpoint as contagens de tokens do prompt e da conclusão no bloco final do fluxo. Desativá-la também faz você perder as contagens de tokens.

Se você hospeda o Dify por conta própria

A stack do Docker Compose encaminha as solicitações de saída por um serviço ssrf_proxy, então o endpoint precisa estar acessível de dentro da rede de contêineres — não basta estar acessível pelo navegador do seu laptop. Se a configuração funciona em um lugar, mas expira por tempo limite no outro, essa costuma ser a causa; trata-se de uma questão de rede, não de credenciais. O curl acima, executado de dentro do contêiner, responde diretamente a essa questão.

Perguntas frequentes

Como conecto uma API personalizada compatível com OpenAI ao Dify?

Instale o plugin OpenAI-API-compatible, publicado por langgenius, em Integrations → Model Provider → Install model providers ou no Dify Marketplace. Clique em Add Model no cartão do plugin e preencha o formulário: Type, Model Name, Model display name, API Key, API Base URL, Completion mode e Model context size, além das opções de compatibilidade. Esse provedor não tem modelos predefinidos — é um provedor de modelos personalizáveis, então cada ID de modelo desejado precisa de uma entrada própria, e cada entrada tem sua própria URL base e chave.

A API Base URL do Dify precisa terminar em /v1?

Sim, para um modelo de chat. O esquema do provedor do plugin identifica o campo como API Base URL, marca-o como obrigatório e mostra o exemplo "Base URL, e.g. https://api.openai.com/v1" como espaço reservado; portanto, a raiz /v1 é o formato documentado — para a Kunavo, https://api.kunavo.com/v1. A origem sem caminho é documentada apenas para os tipos de modelo em que o próprio plugin acrescenta a versão da API, o que, de outro modo, produziria um caminho /v1/v1 duplicado. A Kunavo não oferece modelos desses tipos, então use o formato /v1. Se /v1 estiver ausente, o resultado será um 404, não um erro de autenticação.

Por que meu nó Agent do Dify não consegue usar ferramentas com o modelo que adicionei?

Porque Function Call Type vem definido como no_call em um modelo adicionado pelo plugin OpenAI-API-compatible, e Structured Output, Vision Support, Stream function calling e Thinking Mode Support vêm definidos como não compatíveis. Essas opções são declarações que o Dify considera verdadeiras, não testes; portanto, mesmo um modelo compatível adicionado com os valores padrão será recusado por um nó Agent ou por um nó que use ferramentas. Abra a configuração do modelo e defina Function Call Type como Tool Call — Function Call é o formato antigo — e teste novamente antes de concluir que o problema está no endpoint.

Por que o Dify não mostra o preço de um modelo adicionado pelo plugin compatível?

Porque o esquema do provedor desse plugin não inclui nenhum campo de preço, enquanto os arquivos de modelo predefinidos oficiais do Dify incluem. Por isso, o Dify não tem uma tarifa por token para multiplicar pelas suas contagens e não exibe um valor em vez de uma estimativa. Consulte os valores nos registros de uso do próprio provedor e interprete os números do Dify como contagens de tokens. Deixe Include Usage in Stream ativado para que essas contagens de tokens continuem sendo recebidas.

Adicionar a Kunavo ao Dify é o mesmo que disponibilizar um aplicativo do Dify como API?

Não, e os fluxos seguem direções opostas. Ao adicionar a Kunavo, o Dify se torna o cliente: os nós do Dify enviam solicitações a um endpoint que você configurou com uma chave da Kunavo. Com a Service API do Dify, seu código se torna o cliente: ele chama um aplicativo publicado do Dify usando uma chave emitida pelo Dify, e nenhuma URL base nossa faz parte desse fluxo. É comum um único aplicativo fazer as duas coisas ao mesmo tempo, por isso, se houver um 401, vale rastrear primeiro a chave específica envolvida.

A Kunavo testou essa configuração no Dify?

Não. O que foi verificado em 21 de setembro de 2026 foram os materiais do próprio Dify — a listagem do plugin no Dify Marketplace e o esquema do provedor no repositório oficial de plugins do Dify. É daí que vêm os nomes dos campos, sua ordem, as marcações de obrigatoriedade e os valores padrão citados aqui. Ninguém adicionou um modelo da Kunavo a um workspace ativo do Dify e executou um fluxo de trabalho por meio dele; portanto, não se afirma nada sobre streaming, ciclos de chamada de ferramentas e retorno dos resultados ou ciclos prolongados de agente neste cliente. A única coisa que você pode verificar isoladamente é se o endpoint e a chave funcionam; o comando curl nesta página faz isso.