Skip to main content

Provider Configuration

Providers connect Viben to AI services like Anthropic, OpenAI, Google, and others. This page covers how to configure and manage providers.

Overview​

Provider configuration is stored in ~/.viben/models.yaml. Viben supports multiple authentication methods:

  1. Environment variables (recommended) - No secrets in config files
  2. Command-line - Use --api-key with viben provider create
  3. Config file - Direct values in YAML config

Provider Types​

LLM Providers​

TypeDescriptionAuth
anthropicAnthropic Claude APIAPI Key
openaiOpenAI APIAPI Key
openai-responsesOpenAI Responses APIAPI Key
azureAzure OpenAIAPI Key, Azure AD
googleGoogle AI (Gemini)API Key, OAuth
openrouterOpenRouterAPI Key
ollamaOllama (local)None
volcengineVolcano Engine (字节跳动)API Key
grokGrok (xAI)API Key

Media Providers​

TypeDescriptionAuth
nanobananaNano Banana (image)API Key
imagerouterImage RouterAPI Key
falFal.ai (image/video)API Key
leonardoLeonardo AI (image)API Key
minimaxMiniMax (video/music)API Key
elevenlabsElevenLabs (speech)API Key
fishaudioFish Audio (speech)API Key
senseaudioSenseAudio (speech)API Key
aihubmixAIHubMixAPI Key
sunoSuno (music)API Key
udioUdio (music)API Key

Configuration File​

Basic Structure​

Provider configuration is part of ~/.viben/models.yaml:

# ~/.viben/models.yaml
version: 1

providers:
  anthropic-main:
    type: anthropic
    category: llm
    surfaces: [chat]
    # API key from ANTHROPIC_API_KEY env var

  openai-main:
    type: openai
    category: llm
    surfaces: [chat]
    # API key from OPENAI_API_KEY env var

  dalle-images:
    type: nanobanana
    category: media
    surfaces: [image]

  local-ollama:
    type: ollama
    category: llm
    surfaces: [chat]
    OLLAMA_HOST: "http://localhost:11434"

Provider Categories & Surfaces​

CategoryAvailable Surfaces
llmchat
mediaimage, video, music, speech, sfx

API Key Configuration Methods​

Set environment variables and create providers:

export ANTHROPIC_API_KEY="sk-ant-xxx"
export OPENAI_API_KEY="sk-xxx"

viben provider create -t anthropic
viben provider create -t openai

Method 2: Command-Line​

Provide the API key directly (will be securely stored):

viben provider create -t anthropic --api-key "sk-ant-xxx"

Provider-Specific Configuration​

Anthropic​

Environment VariableDescriptionRequired
ANTHROPIC_API_KEYAPI keyYes
ANTHROPIC_BASE_URLCustom endpointNo

OpenAI​

Environment VariableDescriptionRequired
OPENAI_API_KEYAPI keyYes
OPENAI_BASE_URLCustom endpointNo
OPENAI_ORG_IDOrganization IDNo

Azure OpenAI​

Environment VariableDescriptionRequired
AZURE_OPENAI_API_KEYAzure API keyYes
AZURE_OPENAI_ENDPOINTAzure resource endpointYes
AZURE_OPENAI_API_VERSIONAPI versionYes
AZURE_OPENAI_DEPLOYMENTDeployment nameYes

Google AI (Gemini)​

Environment VariableDescriptionRequired
GOOGLE_API_KEYGoogle AI API keyYes
GOOGLE_PROJECT_IDGCP project IDNo
GOOGLE_LOCATIONRegion locationNo

OpenRouter​

Environment VariableDescriptionRequired
OPENROUTER_API_KEYOpenRouter API keyYes

Ollama (Local)​

Environment VariableDescriptionRequired
OLLAMA_HOSTOllama server URLNo

Grok (xAI)​

Environment VariableDescriptionRequired
XAI_API_KEYxAI API keyYes

Environment Variable Priority​

When resolving API keys, Viben checks in this order:

  1. Command-line argument (--api-key)
  2. Explicit value in config file
  3. Provider-specific environment variable (e.g., ANTHROPIC_API_KEY)
  4. Default base URL (for each provider type)

Provider Commands​

List Providers​

# List all providers
viben provider list

# Filter by category
viben provider list --category media

# Filter by surface
viben provider list --surface image

# JSON output
viben provider list --json

Create Provider​

# Basic creation (uses env vars for API key)
viben provider create -t anthropic

# With explicit name and API key
viben provider create -n my-claude -t anthropic --api-key "sk-ant-xxx"

# Media provider
viben provider create -t nanobanana --category media --surface image --api-key "sk-xxx"

# Set as default
viben provider create -t openai -d

Show Provider​

viben provider show -n anthropic-main

Update Provider​

viben provider update -n my-provider --api-key sk-new-key --timeout 60

Enable / Disable Provider​

viben provider enable -n my-provider
viben provider disable -n my-provider

Remove Provider​

viben provider remove -n my-provider
# or
viben provider rm -n my-provider

Set Default Provider​

viben provider set-default -n openai-main

Check Provider Status​

# All providers
viben provider status

# Specific provider
viben provider status -n anthropic-main

List Supported Types​

viben provider types

Quick Setup Examples​

Minimal Setup (Anthropic Only)​

export ANTHROPIC_API_KEY="sk-ant-xxx"
viben provider create -t anthropic

Multi-Provider Setup​

export ANTHROPIC_API_KEY="sk-ant-xxx"
export OPENAI_API_KEY="sk-xxx"
export GOOGLE_API_KEY="xxx"

viben provider create -t anthropic
viben provider create -t openai
viben provider create -t google

Local Development (Ollama)​

ollama serve
viben provider create -t ollama
viben provider set-default -n ollama-xxx

Media Provider Setup​

export OPENAI_API_KEY="sk-xxx"

viben provider create -t nanobanana --category media --surface image
viben provider create -t elevenlabs --category media --surface speech

Troubleshooting​

Connection Errors​

viben provider status -n anthropic-main
echo $ANTHROPIC_API_KEY

Invalid API Key​

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The API key for provider 'anthropic-main' is invalid"
  }
}

Provider Not Found​

{
  "success": false,
  "error": {
    "code": "PROVIDER_NOT_FOUND",
    "message": "Provider 'unknown' not found in configuration"
  }
}

Next Steps​