> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.empiriolabs.ai/integrations/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.empiriolabs.ai/_mcp/server. # Integrations Most tools only need three values: an API key, a base URL, and a model ID. EmpirioLabs exposes OpenAI-compatible chat completions plus an Anthropic-style Messages endpoint, so setup is usually a provider dropdown and one URL change. #### Fastest setup Run one setup command to create selected local config files. Add user-level tools and a smoke test with flags. #### OpenAI-compatible tools Use `https://api.empiriolabs.ai/v1` as the base URL and your EmpirioLabs key as the bearer token. #### Claude Code Claude Code expects the Anthropic Messages shape. Use `https://api.empiriolabs.ai` without `/v1` and set the custom model option. #### Live model catalog Fetch `GET /v1/models?available=true` before hard-coding model IDs into team templates or shared scripts. [![](https://empiriolabs.ai/images/favicon-192.png)MCP server](#mcp-server) [![](https://opencode.ai/favicon.svg)OpenCode](#opencode) [![](https://cdn.simpleicons.org/anthropic/191919)Claude Code](#claude-code) [![](https://cdn.simpleicons.org/cline/111827)Cline](#cline) [![](https://cdn.simpleicons.org/qwen/6B4DFF)Qwen Code](#qwen-code) [![](https://github.com/openai.png?size=128)Codex CLI](#codex-cli) [![](https://github.com/Aider-AI.png?size=128)Aider](#aider) [![](https://github.com/continuedev.png?size=128)Continue](#continue) [![](https://github.com/OpenHands.png?size=128)OpenHands](#openhands) [![](https://media.empiriolabs.ai/assets/agents/hermes-agent.webp)Hermes Agent](#hermes-agent) [![](https://media.empiriolabs.ai/assets/integrations/openclaw-icon.png)OpenClaw](#openclaw) [![](https://goose-docs.ai/img/favicon.ico)goose](#goose) [![](https://github.com/zed-industries.png?size=128)Zed](#zed) [![](https://github.com/SillyTavern.png?size=128)SillyTavern](#sillytavern) [![](https://personallm.app/favicon.ico?favicon.0b3bf435.ico)PersonaLLM](#personallm) [![](https://ella.janitorai.com/hotlink-ok/apple-touch-icon.png)Janitor AI](#janitor-ai) [![](https://www.typingmind.com/favicon.ico)TypingMind](#typingmind) [![](https://docs.openwebui.com/assets/files/open-webui-icon-115aa34b938cd4b21063a0a1da4c06e0.png)Open WebUI](#open-webui) [![](https://www.librechat.ai/favicon.ico)LibreChat](#librechat) [![](https://github.com/lobehub.png?size=128)LobeChat](#lobechat) [![](https://github.com/langgenius.png?size=128)Dify](#dify) [![](https://github.com/BerriAI.png?size=128)LiteLLM](#litellm) [![](https://haystack.deepset.ai/favicon.ico)Haystack](#haystack) [![](https://github.com/langchain-ai.png?size=128)LangChain](#langchain) [![](https://github.com/langflow-ai.png?size=128)Langflow](#langflow) [![](https://big-agi.com/apple-touch-icon.png)big-AGI](#big-agi) [![](https://media.empiriolabs.ai/assets/integrations/opper-badge.png)Opper](#opper) [![](https://github.com/merge-api.png?size=128)Merge Gateway](#merge-gateway) [![](https://kilo.ai/favicon.ico)![](https://github.com/RooCodeInc.png?size=128)![](https://cdn.simpleicons.org/cursor/111827)Kilo, Roo, Cursor](#kilo-code-roo-code-cursor-and-similar-ides) ## MCP server Claude, ChatGPT, Cursor, VS Code, Codex CLI, and any other Model Context Protocol client can use the whole platform as tools through the remote server at `https://mcp.empiriolabs.ai/mcp`: every chat model, media generation, web search, jobs, batches, GPU Cloud, hosted agents, and account usage. Chat apps sign you in with OAuth; editors and scripts can send an API key as the bearer token instead. Setup steps, profiles, and the full tool reference are on the [MCP Server](/mcp) page. ## Fastest setup Use this when you want a working setup without hand-editing config files. The command fetches the helper script from the docs site, runs it with Python, and writes only the scopes you choose. For tools that support local persisted config, the helper stores the key in gitignored project files so reopened app sessions do not depend on a shell export. #### Run the setup command This default writes project-local files for OpenCode, Aider, Qwen Code, and OpenHands, including gitignored persistent credentials for tools that can read them locally. **`macOS / Linux / WSL`** ```bash title="macOS / Linux / WSL" export EMPIRIOLABS_API_KEY="sk-empiriolabs-your_key_here" script="${TMPDIR:-/tmp}/empirio-integrations-setup.py" curl -fsSL "https://docs.empiriolabs.ai/integrations/setup.py" -o "$script" python3 "$script" \ --scope project \ --tools opencode,aider,qwen-code,openhands \ --model qwen3-7-max ``` **`Windows PowerShell`** ```powershell title="Windows PowerShell" $env:EMPIRIOLABS_API_KEY = "sk-empiriolabs-your_key_here" $script = Join-Path $env:TEMP "empirio-integrations-setup.py" curl.exe -fsSL "https://docs.empiriolabs.ai/integrations/setup.py" -o $script python $script ` --scope project ` --tools opencode,aider,qwen-code,openhands ` --model qwen3-7-max ``` #### Choose scope and tools Change the last flags when you want a different setup: | Goal | Flags | | ---------------------------------------------------- | --------------------------------------------------------------------------- | | Project files only | `--scope project --tools opencode,aider,qwen-code,openhands` | | User-level tools too | `--scope all --tools all` | | One tool only | `--tools opencode`, `--tools claude-code`, or any tool from the table below | | Pick the default model | `--model ` | | Only register the default model (skip auto-populate) | `--no-populate-models` | | Verify key and credits | Add `--smoke-test` | | Print supported tool names | `--list-tools` | The `--tools` flag takes exact, comma-separated values. Do not include spaces unless your shell keeps the whole value quoted. | `--tools` value | Scope | Writes | | --------------- | ------------------- | ------------------------------------------------ | | `opencode` | Project | `opencode.json` plus `.empiriolabs-api-key` | | `aider` | Project | `.aider.empiriolabs.yml` | | `qwen-code` | Project or user | `.qwen/settings.json` or `~/.qwen/settings.json` | | `openhands` | Project | `openhands.empiriolabs.toml` | | `continue` | User | `~/.continue/config.yaml` or sidecar config | | `claude-code` | User | `~/.claude/settings.json` env values | | `codex` | User | Marked block in `~/.codex/config.toml` | | `hermes` | User | `~/.hermes/empiriolabs.config.yaml` sidecar | | `goose` | User | goose custom provider JSON | | `openclaw` | User | `~/.openclaw/empiriolabs.example.json5` sidecar | | `all` | Chosen by `--scope` | Every helper-supported tool for that run | #### Manual download fallback Use this only if your shell blocks remote fetches. Download empirio-integrations-setup.py Asset Then run the helper wherever you want project-local config files: **`macOS / Linux / WSL`** ```bash title="macOS / Linux / WSL" export EMPIRIOLABS_API_KEY="sk-empiriolabs-your_key_here" python3 empirio-integrations-setup.py --scope project --tools opencode,aider,qwen-code,openhands --model qwen3-7-max ``` **`Windows PowerShell`** ```powershell title="Windows PowerShell" $env:EMPIRIOLABS_API_KEY = "sk-empiriolabs-your_key_here" python .\empirio-integrations-setup.py --scope project --tools opencode,aider,qwen-code,openhands --model qwen3-7-max ``` > **Warning** > > The helper creates timestamped backups before changing existing files, but it can write API keys into local `.env`, `.empiriolabs-api-key`, `.qwen/settings.json`, `openhands.empiriolabs.toml`, and some user config files. Review generated files before committing anything. The helper does not install the tools themselves. ## What the helper writes By default the helper fetches the live `/v1/models?available=true` catalog and writes every chat-capable model (text, multimodal, code, reasoning) into tools whose configs natively support a multi-model picker (OpenCode, Continue, Qwen Code, goose). The `--model` flag selects the default within that populated set. Pass `--no-populate-models` if you want only the default model registered. | Tool or file | `--tools` value | Scope | What gets created | | ------------ | ------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Shared env | Always for project scopes | Project | `.env`, `.empiriolabs-api-key`, `empirio-env.sh`, `empirio-env.ps1`, and `.gitignore` entries for local secrets | | OpenCode | `opencode` | Project | `opencode.json` provider named `empiriolabs`, populated with every chat-capable model, reasoning-capable models marked with `reasoning: true`, and pointed at `.empiriolabs-api-key` for persistence | | Aider | `aider` | Project | `.aider.empiriolabs.yml` (single default model, switch via `--model`) | | Qwen Code | `qwen-code` | Project or user | `.qwen/settings.json` or `~/.qwen/settings.json` with one provider entry per chat model, selected OpenAI auth, and fallback `env` values | | OpenHands | `openhands` | Project | `openhands.empiriolabs.toml` plus `LLM_*` values in the generated env files | | Continue | `continue` | User | `~/.continue/config.yaml` or `~/.continue/empiriolabs.config.yaml` `models:` array fully populated, plus `~/.continue/.env` | | Claude Code | `claude-code` | User | `~/.claude/settings.json` env values | | Codex CLI | `codex` | User | Marked block in `~/.codex/config.toml` | | Hermes Agent | `hermes` | User | `~/.hermes/empiriolabs.config.yaml` sidecar and `~/.hermes/.env` | | goose | `goose` | User | Custom provider JSON with every chat-capable model in the `models[]` array | | OpenClaw | `openclaw` | User | `~/.openclaw/empiriolabs.example.json5` sidecar | The helper validates tool names and exits with an error for unknown values. If a selected tool does not match the chosen scope, the helper prints a note. For example, `--scope project --tools codex` does not write Codex config because Codex is a user-level config. Integrations not listed in this table are manual UI or app-level setups. Use the connection values below for Cline, Zed, Kilo Code, Roo Code, Cursor-style fields, chat frontends, and hosted web UIs. ### Refreshing the model list after a new launch The helper fetches `GET /v1/models?available=true` on every run and rewrites the multi-model configs from that live snapshot, so the registered model list reflects whichever models are launched at the moment the helper executes. Re-running the same command after a new model launches adds it to OpenCode's `opencode.json`, Continue's `config.yaml`, the Qwen Code `settings.json` provider list, and the goose custom provider JSON without any other edits. Aider, OpenHands, Claude Code, Codex CLI, Hermes Agent, and OpenClaw do not maintain a multi-model registry in their config, so those tools always read whichever model your code passes at request time, which means no helper re-run is needed for those tools when a new model launches. **`Re-run after a new model launches`** ```bash title="Re-run after a new model launches" export EMPIRIOLABS_API_KEY="sk-empiriolabs-your_key_here" script="${TMPDIR:-/tmp}/empirio-integrations-setup.py" curl -fsSL "https://docs.empiriolabs.ai/integrations/setup.py" -o "$script" python3 "$script" --scope project --tools opencode,aider,qwen-code,openhands --model qwen3-7-max ``` ### Hands-off auto-refresh (installed by default) The setup command installs a platform-native scheduled task that re-fetches the EmpirioLabs model list every 6 hours so newly launched models appear in OpenCode, Qwen Code, Continue, and goose without any manual step. The job runs on its own, in the background, with no shell session required: * **Linux**: a marked entry in your user crontab (visible with `crontab -l`) * **macOS**: a user LaunchAgent at `~/Library/LaunchAgents/ai.empiriolabs.refresh.plist` * **Windows**: a Task Scheduler task named "EmpirioLabs Auto Refresh" The job reads the API key from `~/.empiriolabs/.empiriolabs-api-key` (mode `600` on POSIX) and only rewrites configs that already exist on disk, so it never creates files in unrelated directories. Logs (macOS) and stdout (Linux/Windows) go to `~/.empiriolabs/refresh.log`. Pass `--no-auto-refresh` to the setup command to opt out, or run the helper later with `--uninstall-auto-refresh` to remove the scheduled task and clean up the marker entries. **`Opt out of auto-refresh`** ```bash title="Opt out of auto-refresh" python3 "$script" --scope project --tools opencode,aider,qwen-code,openhands --model qwen3-7-max --no-auto-refresh ``` **`Remove an existing auto-refresh`** ```bash title="Remove an existing auto-refresh" curl -fsSL https://docs.empiriolabs.ai/integrations/setup.py | python3 - --uninstall-auto-refresh ``` ## Connection values | Setting | Use this value | | -------------------------------- | --------------------------------------------------------- | | OpenAI-compatible base URL | `https://api.empiriolabs.ai/v1` | | Anthropic / Claude Code base URL | `https://api.empiriolabs.ai` | | API key | Your dashboard key, usually `sk-empiriolabs-...` | | Authorization header | `Authorization: Bearer $EMPIRIOLABS_API_KEY` | | First model to test | `qwen3-7-max` | | Live model catalog | `GET https://api.empiriolabs.ai/v1/models?available=true` | > **Warning** > > For OpenAI-compatible tools, the base URL should usually end at `/v1`. Do not paste the full `/v1/chat/completions` path into a base URL field unless the tool explicitly asks for a full endpoint URL. ## Thinking and reasoning controls EmpirioLabs exposes reasoning controls only on models that list them in their model page or machine-readable schema. Do not send these fields to every model by default. For OpenAI-compatible Chat Completions and Responses, supported controls can include `enable_thinking`, `thinking_budget`, or `reasoning_effort`, depending on the model: ```json { "model": "qwen3-7-max", "messages": [ { "role": "user", "content": "Answer briefly." } ], "enable_thinking": false } ``` For the Anthropic-style Messages endpoint, use Anthropic-style thinking when the model supports thinking: ```json { "model": "qwen3-7-max", "messages": [ { "role": "user", "content": "Work through this carefully." } ], "thinking": { "type": "enabled", "budget_tokens": 1024 } } ``` `reasoning_effort` accepts `none`, `low`, `medium`, `high`, and `max` on every reasoning-capable model. EmpirioLabs normalizes the value into the selected model's supported reasoning fields, so the same effort string works across model families regardless of whether the model service expects `reasoning_effort`, `enable_thinking`, or `thinking_budget` natively. ```json { "model": "deepseek-v4-pro", "messages": [ { "role": "user", "content": "Solve this carefully." } ], "reasoning_effort": "max" } ``` Tool support varies: | Tool | How to manage reasoning | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | OpenCode | The helper marks reasoning-capable models with `reasoning: true` in `opencode.json`. OpenCode reads its own internal model catalog to decide which effort variants to surface in the `/models` picker for each model ID, so the visible choices differ per family: some models show `none`, `low`, `medium`, `high`, and `max`, while others show only `none`, `low`, `medium`, and `high`. EmpirioLabs accepts every variant OpenCode sends and accepts `max` from any client even when OpenCode does not surface it for that model, so you can pass `reasoning_effort: "max"` directly from custom calls when needed. `none` means no override, so the model default still applies. | | Aider | Use `--reasoning-effort low`, `--reasoning-effort medium`, `--reasoning-effort high`, `/reasoning-effort low`, `--thinking-tokens 0`, or `/thinking-tokens 0` when the selected model supports that control. | | Qwen Code | Provider entries can carry model metadata and generation settings. Keep the helper defaults unless you want to pin a team-wide reasoning mode for one model. | | Codex CLI | Use `model_reasoning_effort` or `plan_mode_reasoning_effort` in `~/.codex/config.toml` for reasoning-capable models. The helper only wires the EmpirioLabs AI provider and leaves the effort unset. | | Chat frontends | Use custom parameters or advanced model settings only when the app exposes them. If it does not, choose a model whose default thinking behavior matches the workflow. | ## Smoke test Run this before configuring a larger tool. If this works, your key, credits, network, and model ID are good. ```bash export EMPIRIOLABS_API_KEY="sk-empiriolabs-your_key_here" curl "https://api.empiriolabs.ai/v1/chat/completions" \ -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "qwen3-7-max", "messages": [ { "role": "user", "content": "Reply with one sentence." } ] }' ``` To list current model IDs: ```bash curl "https://api.empiriolabs.ai/v1/models?available=true" \ -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" ``` ## Chat and roleplay frontends Use this section for BYOK chat apps, roleplay tools, and shared web UIs. These tools normally do not need the helper script. Use your EmpirioLabs API key, pick a chat model such as `qwen3-7-max`, and keep secrets in the app's local settings or environment variables. > **Note** > > For roleplay chats, we generally recommend starting with EmpirioLabs `Native Inference` models first, then models or variants listed in the `Singapore` region when native coverage does not fit your use case. Check the [Models](https://empiriolabs.ai/models) page or [Pricing](https://empiriolabs.ai/pricing) page before choosing a model. Each model lists its served location there. For models with variants, check the variant entries too, since a variant can be served from a different region. | Tool | Endpoint field | Value | | ----------------------- | --------------------------- | ------------------------------------------------ | | SillyTavern | Custom Endpoint / Base URL | `https://api.empiriolabs.ai/v1` | | PersonaLLM | Custom text engine base URL | `https://api.empiriolabs.ai/v1` | | Janitor AI | Proxy URL | `https://api.empiriolabs.ai/v1/chat/completions` | | TypingMind custom model | Endpoint API | `https://api.empiriolabs.ai/v1/chat/completions` | | Open WebUI | OpenAI connection URL | `https://api.empiriolabs.ai/v1` | | LibreChat | `baseURL` | `https://api.empiriolabs.ai/v1` | | LobeChat self-host | `OPENAI_PROXY_URL` | `https://api.empiriolabs.ai/v1` | ### SillyTavern SillyTavern is a local roleplay and character chat frontend. EmpirioLabs works through its custom OpenAI-compatible Chat Completion source. 1. Open SillyTavern and click the plug icon to open API Connections. 2. Set API type to `Chat Completion`. 3. Set Chat Completion Source to `Custom (OpenAI-compatible)`. 4. Set Custom Endpoint / Base URL to `https://api.empiriolabs.ai/v1`. 5. Paste your EmpirioLabs API key into the custom API key field. 6. Click Connect, then choose a model from the dropdown or type a model ID such as `qwen3-7-max`. > **Warning** > > Do not paste `https://api.empiriolabs.ai/v1/chat/completions` into SillyTavern's base URL field. SillyTavern appends the chat completions path itself. If the model dropdown is empty but your smoke test works, type the model ID manually. If a roleplay sampler causes a request error, remove non-standard extra parameters and retry with standard chat settings first. ### PersonaLLM PersonaLLM is an iOS roleplay and character chat app with bring-your-own-key provider settings. EmpirioLabs works through PersonaLLM's custom text engine. 1. From the home screen, tap the three-dot menu in the top left. 2. Open Settings. 3. Open Text Engine. 4. Choose Custom. 5. Set the base URL to `https://api.empiriolabs.ai/v1`. 6. Paste your EmpirioLabs API key. 7. In the models field, tap the button on the right to fetch the live model list. 8. Choose a chat model such as `qwen3-7-max` or `glm-5-1`, then save the text engine settings. > **Note** > > PersonaLLM's thinking toggle sends a reasoning setting when enabled and omits reasoning controls when disabled. EmpirioLabs treats the omitted PersonaLLM field as thinking off only for models whose default is thinking on. This compatibility behavior is scoped to PersonaLLM requests; other tools should send explicit reasoning parameters when they need to override a model default. ### Janitor AI Janitor AI can call EmpirioLabs through its Proxy configuration. Use this path when you want to keep using Janitor's chat UI while bringing your own EmpirioLabs key. 1. Open a Janitor AI chat. 2. Click `using janitor` or the menu button near the top of the chat. 3. Open `API Settings`. 4. Select the `Proxy` tab. 5. In Proxy Configurations, click `+ New`. 6. Set Name to `EmpirioLabs`. 7. Set Model to `qwen3-7-max`, or another model ID from `GET /v1/models?available=true`. 8. Set Proxy URL to `https://api.empiriolabs.ai/v1/chat/completions`. 9. Paste your EmpirioLabs API key into API Key. 10. Leave Custom Prompt blank unless you already use one for that character or chat. 11. Click Add, save the settings, then refresh the Janitor AI page before sending the next message. > **Note** > > If Janitor AI offers a `+ /chat/completions` helper next to the Proxy URL field, start with `https://api.empiriolabs.ai/v1` and let the helper append the path. The saved URL should end in `/v1/chat/completions`. ### TypingMind TypingMind supports custom chat models where you provide an endpoint, model ID, and optional headers. 1. Open `Models` from the left sidebar. 2. Open Model Settings, then click `Add Custom Models`. 3. Use API type `OpenAI Chat Completions API` if the form asks. 4. Set Endpoint API to `https://api.empiriolabs.ai/v1/chat/completions`. 5. Set Model ID to `qwen3-7-max` or another available model. 6. Add header `Authorization: Bearer sk-empiriolabs-your_key_here`, or paste the key into TypingMind's API key field if the form provides one. 7. Click Test, then Add Model. > **Note** > > TypingMind custom model setup is the main exception on this page: it usually asks for the full chat completions endpoint, not just the `/v1` base URL. ### Open WebUI Open WebUI can connect to OpenAI-compatible providers from the admin connection screen. 1. Open Admin Settings. 2. Go to `Connections` and add a new OpenAI connection. 3. Set URL to `https://api.empiriolabs.ai/v1`. 4. Paste your EmpirioLabs API key. 5. If model discovery is slow or too broad, add model IDs such as `qwen3-7-max` to the Model IDs filter. 6. Save, then choose the EmpirioLabs AI model in chat. For server launches, set: ```bash OPENAI_API_BASE_URL=https://api.empiriolabs.ai/v1 OPENAI_API_KEY=sk-empiriolabs-your_key_here ``` ### LibreChat LibreChat supports custom OpenAI-compatible endpoints through `librechat.yaml`. Use an environment variable for one shared deployment key, or `user_provided` if each user should bring their own key in the UI. **`librechat.yaml`** ```yaml title="librechat.yaml" version: 1.3.5 cache: true endpoints: custom: - name: "EmpirioLabs" apiKey: "${EMPIRIOLABS_API_KEY}" baseURL: "https://api.empiriolabs.ai/v1" models: default: ["qwen3-7-max"] fetch: true titleConvo: true titleModel: "qwen3-7-max" modelDisplayLabel: "EmpirioLabs" ``` **`.env`** ```bash title=".env" EMPIRIOLABS_API_KEY=sk-empiriolabs-your_key_here ``` For BYOK multi-user deployments, change `apiKey` to: ```yaml apiKey: "user_provided" ``` Restart LibreChat after changing `librechat.yaml`. ### LobeChat For self-hosted LobeChat, use the OpenAI provider with the EmpirioLabs API base URL: **`.env`** ```bash title=".env" OPENAI_API_KEY=sk-empiriolabs-your_key_here OPENAI_PROXY_URL=https://api.empiriolabs.ai/v1 OPENAI_MODEL_LIST=+qwen3-7-max,+glm-5-1,+deepseek-v4-pro:variant2 ``` Then restart LobeChat and choose an enabled EmpirioLabs model in the model selector. ## Dify Dify can use EmpirioLabs AI through the marketplace model provider plugin. Install the plugin, then add your EmpirioLabs API key in the model provider settings. Open the Dify plugin After installing: 1. Go to **Settings > Model Provider**. 2. Choose the installed provider. 3. Enter your API key. 4. Select a predefined model, or add another model ID. The full list of model IDs is available from [`GET /v1/models`](https://api.empiriolabs.ai/v1/models). ## LiteLLM EmpirioLabs is a built-in LiteLLM provider, so the SDK and the LiteLLM Proxy can route to any EmpirioLabs chat model with the `empiriolabs/` prefix. On LiteLLM versions that predate the provider, use the OpenAI-compatible fallback below. **`LiteLLM SDK`** ```python title="LiteLLM SDK" import os import litellm os.environ["EMPIRIOLABS_API_KEY"] = "sk-empiriolabs-your_key_here" response = litellm.completion( model="empiriolabs/qwen3-7-plus", messages=[{"role": "user", "content": "Hello!"}], ) ``` **`LiteLLM Proxy config.yaml`** ```yaml title="LiteLLM Proxy config.yaml" model_list: - model_name: qwen3-7-plus litellm_params: model: empiriolabs/qwen3-7-plus api_key: os.environ/EMPIRIOLABS_API_KEY ``` Older LiteLLM versions (or image generation) can use the OpenAI-compatible route directly: **`Fallback / image generation`** ```python title="Fallback / image generation" import os import litellm response = litellm.image_generation( prompt="A glass cathedral at sunset, dramatic lighting", model="openai/seedream-5-0-lite", api_base="https://api.empiriolabs.ai/v1", api_key=os.environ["EMPIRIOLABS_API_KEY"], extra_body={"sync": True}, ) ``` The `sync: true` field makes the image endpoint return the finished OpenAI-shaped response instead of the default async job envelope. LiteLLM's own provider page for EmpirioLabs is at [docs.litellm.ai/docs/providers/empiriolabs](https://docs.litellm.ai/docs/providers/empiriolabs). ## Haystack Haystack (by deepset) natively supports EmpirioLabs. Point Haystack's OpenAI components at `https://api.empiriolabs.ai/v1` with your EmpirioLabs key, then use any EmpirioLabs chat or embedding model inside a pipeline. Use `OpenAIChatGenerator` for chat, since the plain `OpenAIGenerator` is deprecated. **`Chat generation`** ```python title="Chat generation" import os from haystack.components.generators.chat import OpenAIChatGenerator from haystack.dataclasses import ChatMessage from haystack.utils import Secret os.environ["EMPIRIOLABS_API_KEY"] = "sk-empiriolabs-your_key_here" generator = OpenAIChatGenerator( api_key=Secret.from_env_var("EMPIRIOLABS_API_KEY"), api_base_url="https://api.empiriolabs.ai/v1", model="qwen3-7-max", ) response = generator.run(messages=[ChatMessage.from_user("Reply with one sentence.")]) print(response["replies"][0].text) ``` **`Embeddings`** ```python title="Embeddings" import os from haystack.components.embedders import OpenAITextEmbedder from haystack.utils import Secret os.environ["EMPIRIOLABS_API_KEY"] = "sk-empiriolabs-your_key_here" embedder = OpenAITextEmbedder( api_key=Secret.from_env_var("EMPIRIOLABS_API_KEY"), api_base_url="https://api.empiriolabs.ai/v1", model="text-embedding-v4", ) result = embedder.run(text="EmpirioLabs gives you frontier models behind one API.") print(len(result["embedding"])) ``` Haystack's integration page for EmpirioLabs is at [haystack.deepset.ai/integrations/empiriolabs](https://haystack.deepset.ai/integrations/empiriolabs). ## LangChain EmpirioLabs AI is a listed provider in LangChain, with `ChatEmpirioLabs` and `EmpirioLabsEmbeddings` in the [provider integrations](https://docs.langchain.com/oss/python/integrations/providers/all_providers). ```bash pip install langchain-empiriolabs ``` **`Chat`** ```python title="Chat" import os from langchain_empiriolabs import ChatEmpirioLabs os.environ["EMPIRIOLABS_API_KEY"] = "sk-empiriolabs-your_key_here" llm = ChatEmpirioLabs(model="qwen3-7-plus") print(llm.invoke("Explain backpropagation in one paragraph.").content) ``` Streaming, tool calling, and `EmpirioLabsEmbeddings` work the same way as any other LangChain chat model. ## Langflow EmpirioLabs AI is a native Langflow integration delivered through Langflow's official extension bundle system. It adds text and image generation components backed by the live EmpirioLabs model catalog. Follow the [official Langflow documentation](https://docs.langflow.org/bundles-empiriolabs) for installation and setup. ## big-AGI big-AGI supports EmpirioLabs AI as an OpenAI-compatible provider. 1. In big-AGI, open **Models** and add a provider. 2. Choose the **OpenAI compatible** type. 3. Set the API host to `https://api.empiriolabs.ai/v1` and paste your API key. EmpirioLabs AI also appears in the provider suggestions. 4. Load the model list to pull the EmpirioLabs catalog. ## Opper [Opper](https://opper.ai) is a European AI gateway based in Stockholm that gives teams one task-centric API across many model providers, with tracing, evaluation, and structured output built in. EmpirioLabs AI is a listed provider, and the listing is live at [opper.ai/provider/empiriolabs](https://opper.ai/provider/empiriolabs). 1. Sign in to Opper and pick an EmpirioLabs AI model from its model catalog, or start from our [provider page](https://opper.ai/provider/empiriolabs). 2. Call the model through the Opper SDK or API. Opper manages the provider connection, so no separate EmpirioLabs key is required there. ## Merge Gateway [Merge Gateway](https://www.merge.dev/gateway) gives Merge customers one API across many models and hosting vendors. EmpirioLabs AI is a hosting vendor on the gateway: for supported models in the [Merge Gateway model catalog](https://docs.merge.dev/merge-gateway/models/catalog), Merge can execute requests on EmpirioLabs AI. Merge manages the provider connection, so no separate EmpirioLabs key is required there. The same models are always available directly through the [EmpirioLabs API](https://docs.empiriolabs.ai). ## OpenCode EmpirioLabs AI is a built-in provider in OpenCode. Run `/connect`, search for **EmpirioLabs AI**, and paste your API key, then run `/models` to choose a model. To register a curated model list or use a file-backed key that survives restarts, the helper can write `opencode.json` for you: ```bash python3 empirio-integrations-setup.py --tools opencode --model qwen3-7-max ``` Manual setup: **`opencode.json`** ```json title="opencode.json" { "$schema": "https://opencode.ai/config.json", "provider": { "empiriolabs": { "npm": "@ai-sdk/openai-compatible", "name": "EmpirioLabs AI", "options": { "baseURL": "https://api.empiriolabs.ai/v1", "apiKey": "{file:.empiriolabs-api-key}" }, "models": { "qwen3-7-plus": { "name": "EmpirioLabs AI Qwen3.7 Plus" }, "qwen3-7-max": { "name": "EmpirioLabs AI Qwen3.7 Max", "reasoning": true } } } } } ``` ```bash printf '%s' 'sk-empiriolabs-your_key_here' > .empiriolabs-api-key printf '\n.empiriolabs-api-key\n' >> .gitignore opencode ``` In OpenCode, run `/models` and choose the EmpirioLabs AI provider. The file-backed key keeps working after you close and reopen OpenCode. ## Claude Code The helper can write the user-level settings automatically: ```bash python3 empirio-integrations-setup.py --scope user --tools claude-code --model qwen3-7-max ``` Claude Code is not an OpenAI-chat-completions client. It talks to LLM gateways through the Anthropic Messages shape, which EmpirioLabs exposes at `/v1/messages`. ```bash export EMPIRIOLABS_API_KEY="sk-empiriolabs-your_key_here" # Claude Code sends ANTHROPIC_AUTH_TOKEN as a Bearer token. export ANTHROPIC_AUTH_TOKEN="$EMPIRIOLABS_API_KEY" # Claude Code appends /v1/messages itself, so do not include /v1 here. export ANTHROPIC_BASE_URL="https://api.empiriolabs.ai" export ANTHROPIC_CUSTOM_MODEL_OPTION="qwen3-7-max" export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="EmpirioLabs AI Qwen3-Max" export ANTHROPIC_MODEL="qwen3-7-max" claude ``` Persistent user-level setup: **`~/.claude/settings.json`** ```json title="~/.claude/settings.json" { "env": { "ANTHROPIC_AUTH_TOKEN": "sk-empiriolabs-your_key_here", "ANTHROPIC_BASE_URL": "https://api.empiriolabs.ai", "ANTHROPIC_CUSTOM_MODEL_OPTION": "qwen3-7-max", "ANTHROPIC_CUSTOM_MODEL_OPTION_NAME": "EmpirioLabs AI Qwen3-Max", "ANTHROPIC_MODEL": "qwen3-7-max" } } ``` > **Note** > > Use a model whose page lists `POST /v1/messages` under supported endpoints. If Claude Code reports a gateway-specific token counting or model discovery error, run it through an Anthropic-format gateway or adapter that implements Claude Code's full gateway contract, then point that gateway at EmpirioLabs. ## Cline In the Cline extension UI: 1. Open Cline settings. 2. Set API Provider to `OpenAI Compatible`. 3. Set Base URL to `https://api.empiriolabs.ai/v1`. 4. Paste your EmpirioLabs API key. 5. Enter a model ID such as `qwen3-7-max`. 6. Click Verify, then start a new task. For Cline CLI: ```bash npm install -g cline export EMPIRIOLABS_API_KEY="sk-empiriolabs-your_key_here" cline auth \ -p openai \ -k "$EMPIRIOLABS_API_KEY" \ -b "https://api.empiriolabs.ai/v1" \ -m "qwen3-7-max" cline "Inspect this repository and suggest the safest next refactor." ``` ## Qwen Code The helper can write project or user settings automatically: ```bash python3 empirio-integrations-setup.py --scope project --tools qwen-code --model qwen3-7-max ``` Launch Qwen Code directly with EmpirioLabs as the OpenAI-compatible provider: ```bash export EMPIRIOLABS_API_KEY="sk-empiriolabs-your_key_here" qwen \ --auth-type openai \ --openaiApiKey "$EMPIRIOLABS_API_KEY" \ --openaiBaseUrl "https://api.empiriolabs.ai/v1" \ --model "qwen3-7-max" ``` For persistent project setup: **`.qwen/settings.json`** ```json title=".qwen/settings.json" { "model": { "name": "qwen3-7-max" }, "security": { "auth": { "selectedType": "openai" } }, "env": { "EMPIRIOLABS_API_KEY": "sk-empiriolabs-your_key_here" }, "modelProviders": { "openai": [ { "id": "qwen3-7-max", "name": "EmpirioLabs AI Qwen3-Max", "envKey": "EMPIRIOLABS_API_KEY", "baseUrl": "https://api.empiriolabs.ai/v1" } ] } } ``` Add `.qwen/settings.json` to `.gitignore` if you store the key there. ## Codex CLI The helper can write the user-level provider block automatically: ```bash python3 empirio-integrations-setup.py --scope user --tools codex --model qwen3-7-max ``` Add EmpirioLabs AI as a custom model provider in `~/.codex/config.toml`: **`~/.codex/config.toml`** ```toml title="~/.codex/config.toml" model = "qwen3-7-max" model_provider = "empiriolabs" [model_providers.empiriolabs] name = "EmpirioLabs AI" base_url = "https://api.empiriolabs.ai/v1" env_key = "EMPIRIOLABS_API_KEY" wire_api = "responses" ``` Then launch Codex with your key in the environment: ```bash export EMPIRIOLABS_API_KEY="sk-empiriolabs-your_key_here" codex ``` Use this path with EmpirioLabs models that support `POST /v1/responses`. ## Aider The helper can write a project-local Aider config automatically: ```bash python3 empirio-integrations-setup.py --tools aider --model qwen3-7-max ``` Aider uses the OpenAI-compatible environment variables. Prefix the model with `openai/`. **`macOS / Linux`** ```bash title="macOS / Linux" export OPENAI_API_BASE="https://api.empiriolabs.ai/v1" export OPENAI_API_KEY="sk-empiriolabs-your_key_here" aider --model openai/qwen3-7-max ``` **`Windows PowerShell`** ```powershell title="Windows PowerShell" $env:OPENAI_API_BASE = "https://api.empiriolabs.ai/v1" $env:OPENAI_API_KEY = "sk-empiriolabs-your_key_here" aider --model openai/qwen3-7-max ``` ## Continue The helper can write the user-level Continue config automatically: ```bash python3 empirio-integrations-setup.py --scope user --tools continue --model qwen3-7-max ``` Continue's OpenAI provider can target any OpenAI-compatible endpoint by setting `apiBase`. Put secrets in `.env` or Continue's secret store rather than committing them into `config.yaml`. **`~/.continue/config.yaml`** ```yaml title="~/.continue/config.yaml" name: EmpirioLabs version: 0.0.1 schema: v1 models: - name: EmpirioLabs AI Qwen3-Max provider: openai model: qwen3-7-max apiBase: https://api.empiriolabs.ai/v1 apiKey: ${{ secrets.EMPIRIOLABS_API_KEY }} capabilities: - tool_use ``` Add the secret in one of Continue's supported `.env` locations: **`~/.continue/.env`** ```bash title="~/.continue/.env" EMPIRIOLABS_API_KEY=sk-empiriolabs-your_key_here ``` ## OpenHands The helper can write a project-local OpenHands config automatically: ```bash python3 empirio-integrations-setup.py --tools openhands --model qwen3-7-max ``` OpenHands exposes provider settings in the UI and passes them through to its LLM layer. | Field | Value | | ------------ | ------------------------------- | | LLM Provider | OpenAI | | LLM Model | `openai/qwen3-7-max` | | API Key | Your EmpirioLabs key | | Base URL | `https://api.empiriolabs.ai/v1` | For environment-based launches: ```bash export LLM_MODEL="openai/qwen3-7-max" export LLM_BASE_URL="https://api.empiriolabs.ai/v1" export LLM_API_KEY="sk-empiriolabs-your_key_here" ``` For persistent project setup: **`openhands.empiriolabs.toml`** ```toml title="openhands.empiriolabs.toml" [llm] model = "openai/qwen3-7-max" api_key = "sk-empiriolabs-your_key_here" base_url = "https://api.empiriolabs.ai/v1" ``` Run OpenHands with: ```bash openhands --config-file openhands.empiriolabs.toml ``` Add `openhands.empiriolabs.toml` to `.gitignore` if you store the key there. ## Hermes Agent The helper can write the user-level Hermes sidecar automatically: ```bash python3 empirio-integrations-setup.py --scope user --tools hermes --model qwen3-7-max ``` Hermes has an interactive model wizard. Choose `Custom endpoint`, then enter: | Prompt | Value | | ------------ | ------------------------------- | | API base URL | `https://api.empiriolabs.ai/v1` | | API key | Your EmpirioLabs key | | Model name | `qwen3-7-max` | Manual config: **`~/.hermes/config.yaml`** ```yaml title="~/.hermes/config.yaml" custom_providers: - name: empiriolabs base_url: https://api.empiriolabs.ai/v1 key_env: EMPIRIOLABS_API_KEY model: provider: custom:empiriolabs default: qwen3-7-max ``` **`~/.hermes/.env`** ```bash title="~/.hermes/.env" EMPIRIOLABS_API_KEY=sk-empiriolabs-your_key_here ``` ## OpenClaw The helper can write a user-level OpenClaw sidecar automatically: ```bash python3 empirio-integrations-setup.py --scope user --tools openclaw --model qwen3-7-max ``` The safest setup is the OpenClaw wizard: ```bash openclaw configure --section model ``` Choose a custom or OpenAI-compatible provider and use: | Field | Value | | ----------- | --------------------------------------------------------------------- | | Provider ID | `empiriolabs` | | API adapter | `openai-completions` | | Base URL | `https://api.empiriolabs.ai/v1` | | API key | SecretRef to `EMPIRIOLABS_API_KEY`, or your key for a local-only test | | Model | `qwen3-7-max` | For manual JSON5 config, use this as a sidecar or merge it into OpenClaw's config: **`~/.openclaw/empiriolabs.example.json5`** ```json5 title="~/.openclaw/empiriolabs.example.json5" { secrets: { providers: { default: { source: "env" } }, defaults: { env: "default" } }, models: { mode: "merge", providers: { empiriolabs: { baseUrl: "https://api.empiriolabs.ai/v1", apiKey: { source: "env", provider: "default", id: "EMPIRIOLABS_API_KEY" }, authHeader: true, api: "openai-completions", models: [ { id: "qwen3-7-max", name: "EmpirioLabs AI Qwen3-Max", input: ["text"], contextWindow: 256000 } ] } } }, agents: { defaults: { model: { primary: "empiriolabs/qwen3-7-max" } } } } ``` Run `openclaw config validate` after manual edits. ## goose EmpirioLabs AI is a built-in provider in goose, so you can pick it directly without writing any custom provider files. It is listed in the [goose providers documentation](https://goose-docs.ai/docs/getting-started/providers/#empiriolabs-ai). Configure it from the goose CLI: ```bash goose configure ``` 1. Select `Configure Providers`. 2. Choose `EmpirioLabs AI` from the provider list. 3. Enter your API key when prompted. goose stores it as `EMPIRIOLABS_API_KEY`. 4. Select the EmpirioLabs AI model you want, for example `qwen3-7-max`. Then start a session: ```bash goose session ``` ### Auto-register every model If you prefer the model picker populated from the live catalog and refreshed as new models launch, the setup helper writes a goose custom provider that lists every chat-capable model: ```bash python3 empirio-integrations-setup.py --scope user --tools goose --model qwen3-7-max ``` The helper writes this as `empiriolabs.json` in the goose custom provider directory. **`empiriolabs.json`** ```json title="empiriolabs.json" { "name": "empiriolabs", "engine": "openai", "display_name": "EmpirioLabs AI", "description": "EmpirioLabs OpenAI-compatible API", "api_key_env": "EMPIRIOLABS_API_KEY", "base_url": "https://api.empiriolabs.ai/v1/chat/completions", "models": [ { "name": "qwen3-7-max", "context_limit": 256000 } ], "supports_streaming": true, "requires_auth": true } ``` ```bash export EMPIRIOLABS_API_KEY="sk-empiriolabs-your_key_here" goose session start --provider empiriolabs ``` ## Zed Zed supports OpenAI-compatible providers in the Agent Panel. Use the UI's `Add Provider` flow, or edit settings: **`Zed settings.json`** ```json title="Zed settings.json" { "language_models": { "openai_compatible": { "EmpirioLabs": { "api_url": "https://api.empiriolabs.ai/v1", "available_models": [ { "name": "qwen3-7-max", "display_name": "EmpirioLabs AI Qwen3-Max", "max_tokens": 256000, "capabilities": { "tools": true, "images": false, "parallel_tool_calls": false, "prompt_cache_key": false } } ] } } } } ``` Add the API key through the Agent Panel so Zed stores it in the OS credential store. ## Kilo Code, Roo Code, Cursor, and similar IDEs Use this table anywhere a tool exposes `OpenAI Compatible`, `Custom OpenAI`, or `Override OpenAI Base URL`. | Field | Value | | -------- | ------------------------------------------- | | Provider | `OpenAI Compatible` | | Base URL | `https://api.empiriolabs.ai/v1` | | API key | Your EmpirioLabs key | | Model | `qwen3-7-max` or another available model ID | Kilo Code and Roo-style VS Code extensions normally expose this as an API configuration profile. Roo Code's public docs and product notices indicate a shutdown/archive path on May 15, 2026, so prefer Cline or Kilo Code for new team-wide templates unless your team already depends on Roo. Cursor's custom API key behavior depends on the version and feature surface. If your Cursor build only accepts provider API keys and does not expose a custom base URL for the feature you want, it cannot be pointed directly at EmpirioLabs for that feature. ## Troubleshooting | Symptom | Fix | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | | `401 Unauthorized` | Check the key, make sure it starts with `sk-empiriolabs-`, and verify the tool is sending it as a bearer token or `x-api-key`. | | `402 Payment Required` | Add credits in the dashboard Billing page. | | `404` or `model_not_found` | Use `GET /v1/models?available=true` and copy the exact `id`. | | Tool says the endpoint is invalid | Use `https://api.empiriolabs.ai/v1` as the base URL, not the full `/chat/completions` URL. | | Agent tool calls are weak or ignored | Pick a model with tool/function-calling support and check `GET /v1/models/{model_id}` for supported parameters. | | Claude Code does not show the model | Set `ANTHROPIC_CUSTOM_MODEL_OPTION` and `ANTHROPIC_MODEL` to the EmpirioLabs model ID. | | Streaming fails in a client | Retry with streaming disabled, then check the model page for streaming support. | ## Keep agents grounded When an AI coding assistant is implementing an EmpirioLabs integration for you, give it the machine-readable docs bundle first: #### [API reference](/api-reference-overview) Endpoint shapes, request bodies, responses, examples, errors, jobs, usage, and saved Playground conversation APIs. #### [AI agent index](/ai-agent-access) Combined context links for the Documentation tab, API Reference tab, and both together. Tell the agent to use `https://docs.empiriolabs.ai/ai-agent-api-reference-context.md` as the API reference, `https://docs.empiriolabs.ai/ai-agent-docs-context.md` for model and pricing details, and `GET https://api.empiriolabs.ai/v1/models/{model_id}` for live model metadata. That prevents the agent from guessing endpoint shapes, stale model IDs, or parameter names. > Connect EmpirioLabs to coding agents, IDEs, CLIs, chat frontends, and OpenAI-compatible tools