> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Dify

> Integre o TokenLab ao Dify usando o provedor OpenAI e uma URL base personalizada

## Visão Geral

O Dify funciona bem com o TokenLab através do seu fluxo de provedor de modelos compatível com OpenAI.

Este é um caminho de integração orientado a chat-completions. Isso não deve ser interpretado como uma garantia de que o Dify exponha as mesmas Respostas ou comportamento de WebSocket que as integrações dedicadas do Codex.

Para as versões atuais do Dify, o caminho mais seguro geralmente é:

* escolher o provedor **OpenAI** integrado
* definir sua chave de API do TokenLab
* definir uma URL base personalizada como `https://api.tokenlab.sh/v1`

<Note>
  Algumas compilações mais antigas do Dify expõem isso como `OpenAI-API-compatible` em vez do provedor `OpenAI` integrado com um campo de URL base personalizada. Se a interface do seu Dify parecer diferente, use o fluxo de provedor personalizado compatível com OpenAI mais próximo disponível nessa versão.
</Note>

<Note>
  **Tipo**: Framework ou Plataforma

  **Caminho Principal**: Caminho de chat compatível com OpenAI

  **Nível de Suporte**: Suportado com limitações de escopo
</Note>

## Pré-requisitos

* Conta no TokenLab com acesso à API
* Dify Cloud ou Dify auto-hospedado

## Etapas de Configuração

### Etapa 1: Obtenha sua Chave de API

1. Faça login no [TokenLab Dashboard](https://tokenlab.sh/dashboard)
2. Abra [API Keys](https://tokenlab.sh/dashboard/api)
3. Crie ou copie uma chave de API que comece com `sk-`

### Etapa 2: Configurar o Provedor

<Steps>
  <Step title="Abrir Provedores de Modelo">
    No Dify, vá para **Settings** → **Model Providers**
  </Step>

  <Step title="Selecionar OpenAI">
    Abra as configurações do provedor **OpenAI**. Se a sua versão do Dify não oferecer uma URL base personalizada aqui, use a opção de provedor personalizado compatível com OpenAI exposta por essa versão.
  </Step>

  <Step title="Inserir Configurações do TokenLab">
    Use estes valores:

    | Campo                          | Valor                        |
    | ------------------------------ | ---------------------------- |
    | API Key                        | `sk-your-tokenlab-key`       |
    | API Base URL / Custom Base URL | `https://api.tokenlab.sh/v1` |
  </Step>

  <Step title="Adicionar Modelos">
    Adicione os modelos que deseja usar, por exemplo:

    * `gpt-5.4`
    * `gpt-5.4-mini`
    * `claude-sonnet-5`
    * `claude-opus-4-8`
    * `gemini-3.5-flash`
    * `gemini-3.1-flash-lite`
    * `deepseek-v4-flash`
  </Step>
</Steps>

### Etapa 3: Testar Conexão

1. Escolha um modelo, como `gpt-5-mini` ou `gpt-4o`
2. Envie um prompt de teste
3. Confirme se o Dify recebe uma resposta válida

## Embeddings para Bases de Conhecimento

Para RAG e indexação de bases de conhecimento, adicione um modelo de embedding como:

* `text-embedding-3-small`
* `text-embedding-3-large`

Em seguida, defina-o como o modelo de embedding padrão nas configurações da base de conhecimento ou do aplicativo relevante.

## Funções de Modelo Recomendadas

| Caso de Uso         | Modelos Sugeridos                                          |
| ------------------- | ---------------------------------------------------------- |
| Chat padrão         | `gpt-5.4-mini`, `gpt-5.4`, `claude-sonnet-5`               |
| Raciocínio profundo | `gpt-5.5`, `gpt-5.4`, `claude-opus-4-8`, `deepseek-v4-pro` |
| Rápido/econômico    | `gpt-5.4-mini`, `gemini-3.5-flash`, `deepseek-v4-flash`    |
| Embeddings          | `text-embedding-3-small`, `text-embedding-3-large`         |

## Melhores Práticas

<AccordionGroup>
  <Accordion title="Comece com o provedor OpenAI integrado">
    Nas versões mais recentes do Dify, o provedor OpenAI integrado com uma URL base personalizada é geralmente a configuração mais limpa para o TokenLab.
  </Accordion>

  <Accordion title="Use modelos mais baratos para iteração">
    Use `gpt-5.4-mini`, `gemini-3.5-flash` ou `deepseek-v4-flash` durante a iteração e, em seguida, alterne fluxos de trabalho mais pesados para modelos mais robustos apenas quando necessário.
  </Accordion>

  <Accordion title="Lembre-se de que o Dify é geralmente orientado a chat-completions">
    A maioria dos fluxos do Dify usa comportamento de chat compatível com OpenAI. Se você precisar de Respostas específicas do Codex ou comportamento de WebSocket, use as integrações dedicadas do Codex em vez do Dify.
  </Accordion>
</AccordionGroup>

## Solução de Problemas

<AccordionGroup>
  <Accordion title="Erro de Conexão">
    * Verifique se a URL base é exatamente `https://api.tokenlab.sh/v1`
    * Remova barras finais se o Dify duplicá-las
    * Confirme se o servidor Dify consegue alcançar o TokenLab pela internet pública
  </Accordion>

  <Accordion title="401 Unauthorized">
    * Verifique novamente a chave de API
    * Confirme se a chave está ativa no dashboard do TokenLab
    * Certifique-se de que o valor colado no Dify não contenha espaços extras ou quebras de linha
  </Accordion>

  <Accordion title="Modelo Não Encontrado">
    * Verifique o nome do modelo exatamente
    * Adicione novamente a entrada do modelo se a interface do provedor tiver armazenado um valor antigo em cache
    * Verifique a disponibilidade atual do modelo na documentação ou no dashboard do TokenLab
  </Accordion>
</AccordionGroup>