> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/moeru-ai/airi/llms.txt
> Use this file to discover all available pages before exploring further.

# Provider Configuration

> Configure LLM, speech synthesis, and transcription providers in Airi

Airi supports 40+ AI providers through the xsAI ecosystem. Providers can be configured for different tasks including chat completion, speech synthesis, transcription, and embeddings.

## Provider Types

Airi organizes providers by task category:

* **Chat Providers**: LLM providers for conversation and reasoning
* **Speech Providers**: Text-to-speech (TTS) services
* **Transcription Providers**: Speech-to-text (STT) and audio recognition
* **Embed Providers**: Text embedding for semantic search

## Available Chat Providers

### Cloud Providers

<AccordionGroup>
  <Accordion title="OpenAI">
    **Provider ID**: `openai`

    Official OpenAI API with GPT models.

    **Configuration**:

    ```json theme={null}
    {
      "apiKey": "sk-...",
      "baseUrl": "https://api.openai.com/v1"
    }
    ```

    **Supported Models**: GPT-4o, GPT-4 Turbo, GPT-3.5 Turbo, and more

    **Features**:

    * Function calling / tool use
    * Vision capabilities (GPT-4o)
    * Streaming responses
    * Context windows up to 128k tokens
  </Accordion>

  <Accordion title="Anthropic (Claude)">
    **Provider ID**: `anthropic`

    Anthropic's Claude models with extended context and reasoning.

    **Configuration**:

    ```json theme={null}
    {
      "apiKey": "sk-ant-...",
      "baseUrl": "https://api.anthropic.com/v1"
    }
    ```

    **Supported Models**: Claude 3.5 Sonnet, Claude 3 Opus, Claude 3 Haiku

    **Features**:

    * 200k+ token context window
    * Tool use
    * Vision capabilities
    * JSON mode
  </Accordion>

  <Accordion title="Google Generative AI (Gemini)">
    **Provider ID**: `google-generative-ai`

    Google's Gemini models via Generative AI API.

    **Configuration**:

    ```json theme={null}
    {
      "apiKey": "AIza..."
    }
    ```

    **Supported Models**: Gemini 2.0, Gemini 1.5 Pro, Gemini 1.5 Flash

    **Features**:

    * Multi-modal inputs (text, images, audio, video)
    * Large context windows (1M+ tokens for Pro)
    * Function calling
    * Real-time responses
  </Accordion>

  <Accordion title="Groq">
    **Provider ID**: `groq`

    Ultra-fast inference with Groq's LPU architecture.

    **Configuration**:

    ```json theme={null}
    {
      "apiKey": "gsk_...",
      "baseUrl": "https://api.groq.com/openai/v1"
    }
    ```

    **Supported Models**: Llama 3.3, Mixtral 8x7B, Gemma 2

    **Features**:

    * Extremely fast token generation (500+ tokens/sec)
    * OpenAI-compatible API
    * Tool use support
  </Accordion>

  <Accordion title="DeepSeek">
    **Provider ID**: `deepseek`

    DeepSeek's cost-effective models with strong reasoning.

    **Configuration**:

    ```json theme={null}
    {
      "apiKey": "sk-...",
      "baseUrl": "https://api.deepseek.com/v1"
    }
    ```

    **Supported Models**: DeepSeek V3, DeepSeek Coder

    **Features**:

    * Cost-effective pricing
    * Strong coding capabilities
    * Extended context
  </Accordion>
</AccordionGroup>

### Router & Aggregator Providers

<AccordionGroup>
  <Accordion title="OpenRouter">
    **Provider ID**: `openrouter-ai`

    Access 100+ models through a unified API with automatic failover.

    **Configuration**:

    ```json theme={null}
    {
      "apiKey": "sk-or-v1-...",
      "baseUrl": "https://openrouter.ai/api/v1"
    }
    ```

    **Features**:

    * Access to 100+ models from different providers
    * Automatic model fallback
    * Per-model pricing
    * Usage credits system
  </Accordion>

  <Accordion title="CometAPI">
    **Provider ID**: `comet-api`

    Multi-model aggregator with simplified billing.

    **Configuration**:

    ```json theme={null}
    {
      "apiKey": "...",
      "baseUrl": "https://api.cometapi.com/v1/"
    }
    ```
  </Accordion>
</AccordionGroup>

### Local & Self-Hosted Providers

<AccordionGroup>
  <Accordion title="Ollama">
    **Provider ID**: `ollama`

    Run open-source models locally.

    **Configuration**:

    ```json theme={null}
    {
      "baseUrl": "http://localhost:11434/v1"
    }
    ```

    **Setup**:

    1. Install Ollama from [https://ollama.ai](https://ollama.ai)
    2. Pull models: `ollama pull llama3.2`
    3. Configure base URL in Airi

    **Popular Models**:

    * `llama3.2:latest` - Meta's Llama 3.2
    * `qwen2.5:latest` - Alibaba's Qwen
    * `phi3:latest` - Microsoft Phi-3
    * `deepseek-coder:latest` - DeepSeek for coding
  </Accordion>

  <Accordion title="OpenAI Compatible">
    **Provider ID**: `openai-compatible`

    Connect to any OpenAI-compatible API (LM Studio, vLLM, LocalAI, etc.).

    **Configuration**:

    ```json theme={null}
    {
      "apiKey": "not-needed",
      "baseUrl": "http://localhost:1234/v1/"
    }
    ```

    **Compatible Services**:

    * LM Studio
    * vLLM
    * LocalAI
    * Text Generation WebUI
    * FastChat
    * Ollama (with OpenAI endpoint)
  </Accordion>
</AccordionGroup>

### Regional & Specialized Providers

<CardGroup cols={2}>
  <Card title="Moonshot AI" icon="moon">
    **Provider ID**: `moonshot-ai`

    Chinese provider with Kimi models.

    ```json theme={null}
    {
      "apiKey": "sk-...",
      "baseUrl": "https://api.moonshot.cn/v1"
    }
    ```
  </Card>

  <Card title="MiniMax" icon="sparkles">
    **Provider ID**: `minimax`

    Chinese multimodal AI provider.

    ```json theme={null}
    {
      "apiKey": "...",
      "groupId": "..."
    }
    ```
  </Card>

  <Card title="302.AI" icon="robot">
    **Provider ID**: `302-ai`

    Multi-model aggregator focused on Chinese market.

    ```json theme={null}
    {
      "apiKey": "sk-...",
      "baseUrl": "https://api.302.ai/v1"
    }
    ```
  </Card>

  <Card title="ModelScope" icon="cube">
    **Provider ID**: `modelscope`

    Alibaba's model hub platform.

    ```json theme={null}
    {
      "apiKey": "..."
    }
    ```
  </Card>
</CardGroup>

## Speech Synthesis Providers

### Commercial TTS Services

<AccordionGroup>
  <Accordion title="ElevenLabs">
    **Provider ID**: `elevenlabs`

    High-quality neural TTS with voice cloning.

    **Configuration**:

    ```json theme={null}
    {
      "apiKey": "...",
      "baseUrl": "https://unspeech.hyp3r.link/v1/",
      "voiceSettings": {
        "stability": 0.5,
        "similarityBoost": 0.75
      }
    }
    ```

    **Supported Models**:

    * `eleven_multilingual_v2` - 29 languages
    * `eleven_turbo_v2_5` - Fastest, low latency
    * `eleven_monolingual_v1` - English only, highest quality

    **Features**:

    * Custom voice cloning
    * Multiple languages
    * Adjustable voice settings
    * Pre-made voice library

    **Voice Settings**:

    * `stability`: 0.0-1.0 (lower = more expressive, higher = more consistent)
    * `similarityBoost`: 0.0-1.0 (how much to boost voice similarity)
  </Accordion>

  <Accordion title="OpenAI TTS">
    **Provider ID**: `openai-audio-speech`

    OpenAI's text-to-speech models.

    **Configuration**:

    ```json theme={null}
    {
      "apiKey": "sk-...",
      "baseUrl": "https://api.openai.com/v1/"
    }
    ```

    **Supported Models**:

    * `tts-1` - Standard quality, fast
    * `tts-1-hd` - High definition audio
    * `gpt-4o-mini-tts` - Latest model with 13 voices

    **Available Voices**: alloy, ash, ballad, coral, echo, fable, nova, onyx, sage, shimmer, verse, marin, cedar
  </Accordion>

  <Accordion title="Microsoft Azure Speech">
    **Provider ID**: `microsoft-speech`

    Azure Cognitive Services TTS.

    **Configuration**:

    ```json theme={null}
    {
      "apiKey": "...",
      "region": "eastus",
      "baseUrl": "https://unspeech.hyp3r.link/v1/"
    }
    ```

    **Features**:

    * 400+ voices in 140+ languages
    * Neural TTS
    * SSML support
    * Custom voice training
  </Accordion>

  <Accordion title="Deepgram TTS">
    **Provider ID**: `deepgram-tts`

    Real-time TTS optimized for conversational AI.

    **Configuration**:

    ```json theme={null}
    {
      "apiKey": "...",
      "baseUrl": "https://unspeech.hyp3r.link/v1/"
    }
    ```

    **Supported Models**:

    * `aura-2` - Latest generation
    * `aura-1` - First generation
  </Accordion>
</AccordionGroup>

### Open-Source & Local TTS

<AccordionGroup>
  <Accordion title="Browser (Local)">
    **Provider ID**: `browser-local-audio-speech`

    In-browser TTS using WebGPU (no API key required).

    **Requirements**:

    * Modern browser with WebGPU support
    * At least 8GB RAM
    * GPU recommended

    **Configuration**:

    ```json theme={null}
    {
      "baseUrl": "auto-configured"
    }
    ```

    **Features**:

    * No internet required
    * Privacy-first (all processing local)
    * No API costs
  </Accordion>

  <Accordion title="Index-TTS (Bilibili)">
    **Provider ID**: `index-tts-vllm`

    Open-source Chinese/English TTS.

    **Configuration**:

    ```json theme={null}
    {
      "baseUrl": "http://localhost:11996/tts/"
    }
    ```

    **Setup**:

    ```bash theme={null}
    # Install from https://index-tts.github.io
    # Run the server
    index-tts-server --port 11996
    ```
  </Accordion>

  <Accordion title="App (Local) - Desktop Only">
    **Provider ID**: `app-local-audio-speech`

    Native desktop TTS using Hugging Face Candle.

    **Features**:

    * CUDA/Metal acceleration
    * No internet required
    * Optimized for desktop
  </Accordion>
</AccordionGroup>

## Transcription Providers

<AccordionGroup>
  <Accordion title="OpenAI Whisper">
    **Provider ID**: `openai-audio-transcription`

    OpenAI's Whisper transcription models.

    **Configuration**:

    ```json theme={null}
    {
      "apiKey": "sk-...",
      "baseUrl": "https://api.openai.com/v1/"
    }
    ```

    **Supported Models**:

    * `whisper-1` - Original Whisper V2
    * `gpt-4o-transcribe` - Latest, higher quality
    * `gpt-4o-mini-transcribe` - Faster, cost-effective
    * `gpt-4o-transcribe-diarize` - With speaker diarization
  </Accordion>

  <Accordion title="Web Speech API">
    **Provider ID**: `browser-web-speech-api`

    Browser-native speech recognition (Chrome, Edge, Safari).

    **Requirements**:

    * Supported browser (not available in Electron/Tamagotchi)
    * Internet connection (uses browser's API)

    **Configuration**:

    ```json theme={null}
    {
      "language": "en-US",
      "continuous": true,
      "interimResults": true,
      "maxAlternatives": 1
    }
    ```

    **Features**:

    * No API key required
    * Real-time streaming
    * No cost
    * Automatic punctuation
  </Accordion>

  <Accordion title="Aliyun NLS">
    **Provider ID**: `aliyun-nls-transcription`

    Alibaba Cloud real-time speech recognition.

    **Configuration**:

    ```json theme={null}
    {
      "accessKeyId": "...",
      "accessKeySecret": "...",
      "appKey": "...",
      "region": "cn-shanghai"
    }
    ```

    **Features**:

    * WebSocket streaming
    * Real-time transcription
    * Chinese language optimized
  </Accordion>

  <Accordion title="Browser/App Local Transcription">
    **Provider IDs**:

    * `browser-local-audio-transcription` - WebGPU in browser
    * `app-local-audio-transcription` - Native on desktop

    Local speech recognition using Whisper models.

    **Configuration**: Auto-configured, no API key needed

    **Requirements**:

    * WebGPU support or GPU
    * Sufficient RAM (4GB+)
  </Accordion>
</AccordionGroup>

## Provider Configuration Guide

### Adding a Provider

Providers can be added through:

1. **Settings UI** (Recommended):
   * Navigate to Settings → Providers
   * Click "Add Provider"
   * Select provider type and task
   * Fill in credentials
   * Validate and save

2. **Programmatic** (Advanced):

```typescript theme={null}
import { useProviderCatalogStore } from '@proj-airi/stage-ui'

const store = useProviderCatalogStore()
await store.addProvider('openai', {
  apiKey: 'sk-...',
  baseUrl: 'https://api.openai.com/v1'
})
```

### Configuration Schema

Each provider uses Zod schema validation. Common fields:

```typescript theme={null}
{
  apiKey: string        // API key (most providers)
  baseUrl: string       // API endpoint URL
  headers?: Record<string, string>  // Custom headers
  timeout?: number      // Request timeout in ms
}
```

Provider-specific schemas are defined in `packages/stage-ui/src/libs/providers/providers/`.

### Validation

Providers are validated before use:

* **Config Validation**: Checks required fields and format
* **Connectivity Validation**: Tests API connection
* **Model List Validation**: Verifies model availability
* **Chat Completions Validation**: Tests actual inference

Validation can be bypassed for advanced users, but may cause runtime errors.

### Rate Limits & Quotas

<Warning>
  Most cloud providers enforce rate limits. Monitor your usage to avoid hitting limits:

  * **OpenAI**: 3,500 RPM (requests/min) for free tier
  * **Anthropic**: 50 RPM for free tier
  * **Groq**: 30 RPM for free tier
  * **ElevenLabs**: 10,000 characters/month free
</Warning>

Local providers have no rate limits.

## Advanced Configuration

### Custom Headers

Add custom headers for proxy or authentication:

```json theme={null}
{
  "apiKey": "sk-...",
  "baseUrl": "https://api.openai.com/v1",
  "headers": {
    "X-Custom-Header": "value",
    "Authorization": "Bearer token"
  }
}
```

### Proxy Configuration

For providers behind a proxy:

```json theme={null}
{
  "baseUrl": "http://your-proxy.com/openai/v1",
  "apiKey": "sk-..."
}
```

### Multiple Provider Instances

You can add multiple instances of the same provider with different configs:

```typescript theme={null}
// Production OpenAI
await store.addProvider('openai', {
  apiKey: 'sk-prod-...',
  baseUrl: 'https://api.openai.com/v1'
})

// Development OpenAI (different key)
await store.addProvider('openai', {
  apiKey: 'sk-dev-...',
  baseUrl: 'https://api.openai.com/v1'
})
```

Each instance gets a unique ID.

## Provider Capabilities

Different providers support different features:

| Provider              | Function Calling | Vision | Streaming | Max Context |
| --------------------- | ---------------- | ------ | --------- | ----------- |
| OpenAI GPT-4o         | ✅                | ✅      | ✅         | 128k        |
| Anthropic Claude 3.5  | ✅                | ✅      | ✅         | 200k        |
| Google Gemini 1.5 Pro | ✅                | ✅      | ✅         | 1M          |
| Groq Llama 3.3        | ✅                | ❌      | ✅         | 8k          |
| Ollama (local)        | ✅\*              | ✅\*    | ✅         | Varies      |

\*Depends on specific model

## Troubleshooting

### Provider Not Available

Some providers are platform-specific:

* `app-*` providers: Desktop (Tamagotchi) only
* `browser-*` providers: Web only
* `web-speech-api`: Browser only (not in Electron)

### Connection Failed

1. Check your internet connection
2. Verify API key is correct
3. Ensure base URL has trailing slash `/`
4. Check firewall/proxy settings
5. Verify the provider service is operational

### Invalid API Key

* Check for extra spaces or newlines
* Verify key hasn't expired
* Ensure key has proper permissions
* Try regenerating the key from provider dashboard

### Rate Limit Errors

* Wait before retrying
* Upgrade to paid tier
* Use local/self-hosted alternative
* Distribute load across multiple providers

### Model Not Found

* Refresh model list in settings
* Verify model is available in your region
* Check if model requires special access
* Try using a different model

## Code Reference

Provider system implementation:

* Provider definitions: `packages/stage-ui/src/libs/providers/providers/`
* Provider store: `packages/stage-ui/src/stores/providers.ts`
* Provider catalog: `packages/stage-ui/src/stores/provider-catalog.ts`
* Provider types: `packages/stage-ui/src/libs/providers/types.ts`

## Related Resources

<CardGroup cols={2}>
  <Card title="Voice Synthesis" icon="microphone" href="/configuration/voice-synthesis">
    Configure TTS providers and voices
  </Card>

  <Card title="Character Settings" icon="user" href="/configuration/character-settings">
    Link models to character cards
  </Card>

  <Card title="Memory System" icon="database" href="/configuration/memory">
    Configure conversation memory
  </Card>
</CardGroup>