Skip to main content

Adding a Provider

By adding providers, you can connect different LLM services to Elftia and freely switch between models during chat. Elftia offers three methods: preset templates, custom configuration, and import/export.

When to Use​

  • You are setting up Elftia for the first time and need to configure an API key to enable the default providers
  • You need to connect to an LLM service that is not in the default list
  • You want to add multiple instances of the same provider (e.g. endpoints in different regions)
  • You are migrating your configuration from another device

Method 1: Add from a Preset Template​

Preset templates include the provider's Base URL, default model list, and recommended configuration — you only need to fill in your API key to complete the setup.

Steps​

  1. Open Settings → Provider Management
  2. Click the Add Provider button
  3. Select a preset template from the provider list
  1. In the configuration panel that appears, enter your API Key
    • Paste the key value directly, e.g. sk-xxxxxxxxxxxxxxxx
    • Or reference an environment variable, e.g. $OPENAI_API_KEY

  1. Click Test Connection to confirm the key is valid

    • Success: a green message "Connection successful" is displayed
    • Failure: an error message is shown (see Troubleshooting)

  2. Enable the Enabled toggle

  3. Click Save

Once done, the provider's models will appear in the model selection dropdown in the chat UI.

Preset Template Reference​

International Providers​

Preset IDNameAPI FormatBase URLHighlights
openaiOpenAIopenaihttps://api.openai.com/v1/chat/completionsGPT-4o/5, o1/o3 reasoning series, vision support
anthropicAnthropicanthropichttps://api.anthropic.com/v1/messagesClaude Sonnet/Opus/Haiku 4.5, native chain-of-thought
geminiGoogle Geminigooglehttps://generativelanguage.googleapis.com/v1beta/models/1M-token context, vision + reasoning
openai-responseOpenAI (Responses API)openai-responsehttps://api.openai.comGPT-5 series + o3/o4, new API
azure-openaiAzure OpenAIazure-openai(custom)Enterprise SLA; deployment name used as model
openrouterOpenRouteropenaihttps://openrouter.ai/api/v1Aggregates 200+ models with a single key
groqGroqopenaihttps://api.groq.com/openai/v1Ultra-fast inference engine
ollamaOllamaopenaihttp://localhost:11434/v1Local deployment, free to use

Chinese Cloud Platforms​

Preset IDNameAPI FormatBase URLHighlights
zhipuZhipu GLMopenaihttps://api.z.ai/api/paas/v4GLM-5/4.5/4.6V/4.7, Coding Plan
volcengineVolcengine (Ark)openaihttps://ark.cn-beijing.volces.com/api/v3Doubao Seed 2.0, intelligent routing, multi-model aggregation
kimiKimi (Moonshot)openaihttps://api.moonshot.ai/v1Kimi K2.5, 256K context
dashscopeAlibaba Cloud Bailianopenaihttps://dashscope.aliyuncs.com/compatible-mode/v1Qwen3 series, 1M tokens
tencentTencent Cloud Hunyuanopenaihttps://api.lkeap.cloud.tencent.com/v1Hunyuan 2.0, multi-model aggregation
minimaxMiniMaxanthropichttps://api.minimaxi.com/anthropicM2.5/M2.1, Anthropic format
baiduBaidu Qianfanopenaihttps://qianfan.baidubce.com/v2ERNIE series, Coding Plan
kuaishouKuaishou KwaiKATopenaihttps://wanqing.streamlakeapi.com/api/gateway/v1KAT-Coder, optimized for coding
mthreadsMoore Threadsopenai(requires configuration)Domestic chip Coding Plan

Method 2: Custom OpenAI-Compatible Provider​

If the LLM service you use provides an OpenAI-compatible API (most services do), you can add it as a custom provider.

Steps​

  1. Open Settings → Provider Management
  2. Click Add Provider → select Custom Provider
  1. Fill in the basic information:
FieldRequiredDescriptionExample
NameYesDisplay nameMy Local LLM
API FormatYesSelect the protocol formatopenai (most common)
Base URLYesAPI addresshttp://localhost:8080/v1/chat/completions
API KeyNoAuthentication keysk-... (can be left empty for local services)
  1. Add models:
    • Click Add Model
    • Enter the model ID (the name used when calling the API, e.g. llama-3.1-70b)
    • Enter the display name
    • Set model capability flags (vision, function calling, reasoning, etc.)

  1. (Optional) Configure a Transformer:

    • If the target service's API differs from the standard OpenAI format, add an appropriate transformer
    • Common choices: deepseek (for DeepSeek-compatible services), groq (for Groq-compatible services)

  2. Click Test Connection to verify the configuration

  3. Enable the Enabled toggle and save

Model Discovery​

Some providers support automatic model discovery via the /v1/models endpoint:

  1. In the provider configuration, fill in the Model Discovery Endpoint (e.g. https://api.example.com/v1/models)
  2. Click the Discover Models button
  3. Elftia calls the endpoint to fetch the model list
  4. Select the models you want to add from the returned results

Method 3: Import / Export​

Exporting a Configuration​

  1. Open Settings → Provider Management
  2. Select the provider you want to export
  3. Click the Export button
  4. The configuration is saved as a JSON file

Importing a Configuration​

  1. Open Settings → Provider Management
  2. Click the Import button
  3. Select the previously exported JSON file
  4. Review the imported provider information
  5. Enter the API key (for security reasons, the exported file does not include the API key)
  6. Save and enable

Environment Variable API Keys​

Using environment variables to manage API keys is the recommended approach, especially in the following scenarios:

  • You prefer not to store the key in plaintext in the application database
  • You share configuration files across multiple devices, each using a different key
  • You use Elftia in CI/CD or automation scenarios

How to Configure​

In the API key input field, enter the environment variable name prefixed with $:

Input valueResolved at runtime to
$OPENAI_API_KEYThe value of process.env.OPENAI_API_KEY
$ANTHROPIC_API_KEYThe value of process.env.ANTHROPIC_API_KEY
$MY_CUSTOM_KEYThe value of process.env.MY_CUSTOM_KEY

Note: if the corresponding environment variable is not set, API requests will fail with an authentication error. You must restart Elftia after changing environment variables for the new values to take effect.

Configuration Reference​

SettingTypeDefaultDescription
NameString(template name)Provider display name
API FormatEnumopenaiopenai / anthropic / google / azure-openai / openai-response
Base URLURL(varies by template)API request address; must start with http:// or https://
API KeyString(empty)Supports $ prefix to reference environment variables
Model listArray(varies by template)Can be added, removed, or fetched via model discovery
Model discovery endpointURL(optional)Call /v1/models or similar endpoints to auto-fetch the model list
EnabledBooleanfalseNewly added providers are disabled by default
TransformerArray(varies by format)Request/response format transformer chain
IconString(varies by template)Provider icon identifier
Website linkURL(optional)Provider's website, used for documentation links
NotesString(empty)Free-form notes
API VersionString(Azure only)API version number for Azure OpenAI
Concurrency limitNumber(varies by provider)Maximum concurrent requests in Agent mode
Is officialBooleanfalseMarks the provider as an official Anthropic provider (affects chain-of-thought signature handling)

Behavior Notes​

Preset Templates vs. Custom Providers​

FeaturePreset templateCustom provider
Base URLAuto-filledMust be entered manually
Model listPre-configuredMust be added manually
TransformerAuto-configuredOptional
Model discoverySupported for someMust set endpoint manually
Coding PlanSupported for someNot supported
Search integrationPre-configuredMust be configured manually

Provider ID Uniqueness​

Each provider has a unique ID. When adding multiple instances from the same preset template, Elftia automatically appends a suffix to the ID to ensure uniqueness.

Initial State After Adding​

A newly added provider is disabled by default. You must:

  1. Enter a valid API key
  2. Successfully test the connection
  3. Manually enable the toggle

before you can use that provider's models in chat.

Troubleshooting​

IssuePossible causeSolution
Test connection returns 401API key is invalid or expiredRegenerate the key on the provider's website
Test connection returns 403Key lacks permissionConfirm the key has access to the target model
Test connection times outNo network connection or incorrect Base URLCheck network connectivity and URL spelling
$ENV_VAR key is invalidEnvironment variable is not setSet the environment variable in the system and restart Elftia
Model discovery returns an empty listIncorrect endpoint or key lacks permissionCheck the model discovery endpoint URL; confirm the key has list-models permission
Save fails with invalid URL errorBase URL format is incorrectMake sure it starts with http:// or https://
Custom provider requests failTransformer configuration mismatchConfirm the API format selection is correct, or try adding the corresponding transformer
Azure OpenAI connection failsIncorrect API version or deployment nameConfirm the API Version field is filled in (e.g. 2024-08-01-preview); use the deployment name as the model name
MiniMax request format errorNot using anthropic formatMiniMax uses the Anthropic API format — select anthropic and configure the anthropic transformer