> ## 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

> Integrate TokenLab with Dify using the OpenAI provider and a custom base URL

## Overview

Dify works well with TokenLab through its OpenAI-compatible model provider flow.

This is a chat-completions-oriented integration path. It should not be read as a guarantee that Dify exposes the same Responses or WebSocket behavior as dedicated Codex integrations.

For current Dify versions, the safest path is usually:

* choose the built-in **OpenAI** provider
* set your TokenLab API key
* set a custom base URL of `https://api.tokenlab.sh/v1`

<Note>
  Some older Dify builds expose this as `OpenAI-API-compatible` instead of the built-in `OpenAI` provider with a custom base URL field. If your Dify UI looks different, use the closest OpenAI-compatible custom provider flow available in that version.
</Note>

<Note>
  **Type**: Framework or Platform

  **Primary Path**: OpenAI-compatible chat path

  **Support Confidence**: Supported with scope limits
</Note>

## Prerequisites

* TokenLab account with API access
* Dify Cloud or self-hosted Dify

## Configuration Steps

### Step 1: Get Your API Key

1. Log into [TokenLab Dashboard](https://tokenlab.sh/dashboard)
2. Open [API Keys](https://tokenlab.sh/dashboard/api)
3. Create or copy an API key that starts with `sk-`

### Step 2: Configure the Provider

<Steps>
  <Step title="Open Model Providers">
    In Dify, go to **Settings** → **Model Providers**
  </Step>

  <Step title="Select OpenAI">
    Open the **OpenAI** provider settings. If your Dify version does not offer a custom base URL here, use the OpenAI-compatible custom provider option exposed by that version instead.
  </Step>

  <Step title="Enter TokenLab Settings">
    Use these values:

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

  <Step title="Add Models">
    Add the models you want to use, for example:

    * `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>

### Step 3: Test Connection

1. Pick one model such as `gpt-5-mini` or `gpt-4o`
2. Send a test prompt
3. Confirm Dify receives a valid response

## Embeddings for Knowledge Bases

For RAG and knowledge base indexing, add an embedding model such as:

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

Then set it as the default embedding model in the relevant knowledge base or application settings.

## Recommended Model Roles

| Use Case       | Suggested Models                                           |
| -------------- | ---------------------------------------------------------- |
| Default chat   | `gpt-5.4-mini`, `gpt-5.4`, `claude-sonnet-5`               |
| Deep reasoning | `gpt-5.5`, `gpt-5.4`, `claude-opus-4-8`, `deepseek-v4-pro` |
| Fast/cheap     | `gpt-5.4-mini`, `gemini-3.5-flash`, `deepseek-v4-flash`    |
| Embeddings     | `text-embedding-3-small`, `text-embedding-3-large`         |

## Best Practices

<AccordionGroup>
  <Accordion title="Start with the built-in OpenAI provider">
    In newer Dify versions, the built-in OpenAI provider with a custom base URL is usually the cleanest setup for TokenLab.
  </Accordion>

  <Accordion title="Use cheaper models for iteration">
    Use `gpt-5.4-mini`, `gemini-3.5-flash`, or `deepseek-v4-flash` while iterating, then switch heavier workflows to stronger models only where needed.
  </Accordion>

  <Accordion title="Remember Dify is usually chat-completions oriented">
    Most Dify flows use OpenAI-compatible chat behavior. If you need Codex-specific Responses or WebSocket behavior, use the dedicated Codex integrations instead of Dify.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection Error">
    * Verify the base URL is exactly `https://api.tokenlab.sh/v1`
    * Remove trailing slashes if Dify duplicates them
    * Confirm the Dify server can reach TokenLab over the public internet
  </Accordion>

  <Accordion title="401 Unauthorized">
    * Double-check the API key
    * Confirm the key is active in TokenLab dashboard
    * Make sure the value pasted into Dify does not contain extra spaces or line breaks
  </Accordion>

  <Accordion title="Model Not Found">
    * Verify the model name exactly
    * Re-add the model entry if the provider UI cached an older value
    * Check current model availability in TokenLab docs or dashboard
  </Accordion>
</AccordionGroup>