Provider Configuration

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

OpenAI

Provider ID: openaiOfficial OpenAI API with GPT models.Configuration:

{
  "apiKey": "sk-...",
  "baseUrl": "https://api.openai.com/v1"
}

Supported Models: GPT-4o, GPT-4 Turbo, GPT-3.5 Turbo, and moreFeatures:

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

Anthropic (Claude)

Provider ID: anthropicAnthropic’s Claude models with extended context and reasoning.Configuration:

{
  "apiKey": "sk-ant-...",
  "baseUrl": "https://api.anthropic.com/v1"
}

Supported Models: Claude 3.5 Sonnet, Claude 3 Opus, Claude 3 HaikuFeatures:

200k+ token context window
Tool use
Vision capabilities
JSON mode

Google Generative AI (Gemini)

Provider ID: google-generative-aiGoogle’s Gemini models via Generative AI API.Configuration:

{
  "apiKey": "AIza..."
}

Supported Models: Gemini 2.0, Gemini 1.5 Pro, Gemini 1.5 FlashFeatures:

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

Groq

Provider ID: groqUltra-fast inference with Groq’s LPU architecture.Configuration:

{
  "apiKey": "gsk_...",
  "baseUrl": "https://api.groq.com/openai/v1"
}

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

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

DeepSeek

Provider ID: deepseekDeepSeek’s cost-effective models with strong reasoning.Configuration:

{
  "apiKey": "sk-...",
  "baseUrl": "https://api.deepseek.com/v1"
}

Supported Models: DeepSeek V3, DeepSeek CoderFeatures:

Cost-effective pricing
Strong coding capabilities
Extended context

Router & Aggregator Providers

OpenRouter

Provider ID: openrouter-aiAccess 100+ models through a unified API with automatic failover.Configuration:

{
  "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

CometAPI

Provider ID: comet-apiMulti-model aggregator with simplified billing.Configuration:

{
  "apiKey": "...",
  "baseUrl": "https://api.cometapi.com/v1/"
}

Local & Self-Hosted Providers

Ollama

Provider ID: ollamaRun open-source models locally.Configuration:

{
  "baseUrl": "http://localhost:11434/v1"
}

Setup:

Install Ollama from https://ollama.ai
Pull models: ollama pull llama3.2
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

OpenAI Compatible

Provider ID: openai-compatibleConnect to any OpenAI-compatible API (LM Studio, vLLM, LocalAI, etc.).Configuration:

{
  "apiKey": "not-needed",
  "baseUrl": "http://localhost:1234/v1/"
}

Compatible Services:

LM Studio
vLLM
LocalAI
Text Generation WebUI
FastChat
Ollama (with OpenAI endpoint)

Regional & Specialized Providers

Moonshot AI

Provider ID: moonshot-aiChinese provider with Kimi models.

{
  "apiKey": "sk-...",
  "baseUrl": "https://api.moonshot.cn/v1"
}

MiniMax

Provider ID: minimaxChinese multimodal AI provider.

{
  "apiKey": "...",
  "groupId": "..."
}

302.AI

Provider ID: 302-aiMulti-model aggregator focused on Chinese market.

{
  "apiKey": "sk-...",
  "baseUrl": "https://api.302.ai/v1"
}

ModelScope

Provider ID: modelscopeAlibaba’s model hub platform.

{
  "apiKey": "..."
}

Speech Synthesis Providers

Commercial TTS Services

ElevenLabs

Provider ID: elevenlabsHigh-quality neural TTS with voice cloning.Configuration:

{
  "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)

OpenAI TTS

Provider ID: openai-audio-speechOpenAI’s text-to-speech models.Configuration:

{
  "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

Microsoft Azure Speech

Provider ID: microsoft-speechAzure Cognitive Services TTS.Configuration:

{
  "apiKey": "...",
  "region": "eastus",
  "baseUrl": "https://unspeech.hyp3r.link/v1/"
}

Features:

400+ voices in 140+ languages
Neural TTS
SSML support
Custom voice training

Deepgram TTS

Provider ID: deepgram-ttsReal-time TTS optimized for conversational AI.Configuration:

{
  "apiKey": "...",
  "baseUrl": "https://unspeech.hyp3r.link/v1/"
}

Supported Models:

aura-2 - Latest generation
aura-1 - First generation

Open-Source & Local TTS

Browser (Local)

Provider ID: browser-local-audio-speechIn-browser TTS using WebGPU (no API key required).Requirements:

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

Configuration:

{
  "baseUrl": "auto-configured"
}

Features:

No internet required
Privacy-first (all processing local)
No API costs

Index-TTS (Bilibili)

Provider ID: index-tts-vllmOpen-source Chinese/English TTS.Configuration:

{
  "baseUrl": "http://localhost:11996/tts/"
}

Setup:

# Install from https://index-tts.github.io
# Run the server
index-tts-server --port 11996

App (Local) - Desktop Only

Provider ID: app-local-audio-speechNative desktop TTS using Hugging Face Candle.Features:

CUDA/Metal acceleration
No internet required
Optimized for desktop

Transcription Providers

OpenAI Whisper

Provider ID: openai-audio-transcriptionOpenAI’s Whisper transcription models.Configuration:

{
  "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

Web Speech API

Provider ID: browser-web-speech-apiBrowser-native speech recognition (Chrome, Edge, Safari).Requirements:

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

Configuration:

{
  "language": "en-US",
  "continuous": true,
  "interimResults": true,
  "maxAlternatives": 1
}

Features:

No API key required
Real-time streaming
No cost
Automatic punctuation

Aliyun NLS

Provider ID: aliyun-nls-transcriptionAlibaba Cloud real-time speech recognition.Configuration:

{
  "accessKeyId": "...",
  "accessKeySecret": "...",
  "appKey": "...",
  "region": "cn-shanghai"
}

Features:

WebSocket streaming
Real-time transcription
Chinese language optimized

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 neededRequirements:

WebGPU support or GPU
Sufficient RAM (4GB+)

Provider Configuration Guide

Adding a Provider

Providers can be added through:

Settings UI (Recommended):
- Navigate to Settings → Providers
- Click “Add Provider”
- Select provider type and task
- Fill in credentials
- Validate and save
Programmatic (Advanced):

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:

{
  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

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

Local providers have no rate limits.

Advanced Configuration

Custom Headers

Add custom headers for proxy or authentication:

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

Proxy Configuration

For providers behind a proxy:

{
  "baseUrl": "http://your-proxy.com/openai/v1",
  "apiKey": "sk-..."
}

Multiple Provider Instances

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

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

Check your internet connection
Verify API key is correct
Ensure base URL has trailing slash /
Check firewall/proxy settings
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

Voice Synthesis

Configure TTS providers and voices

Character Settings

Link models to character cards

Memory System

Configure conversation memory

Get Started

Core Features

Platforms

Integrations

Configuration

Development

​Provider Types

​Available Chat Providers

​Cloud Providers

​Router & Aggregator Providers

​Local & Self-Hosted Providers

​Regional & Specialized Providers

Moonshot AI

MiniMax

302.AI

ModelScope

​Speech Synthesis Providers

​Commercial TTS Services

​Open-Source & Local TTS

​Transcription Providers

​Provider Configuration Guide

​Adding a Provider

​Configuration Schema

​Validation

​Rate Limits & Quotas

​Advanced Configuration

​Custom Headers

​Proxy Configuration

​Multiple Provider Instances

​Provider Capabilities

​Troubleshooting

​Provider Not Available

​Connection Failed

​Invalid API Key

​Rate Limit Errors

​Model Not Found

​Code Reference

​Related Resources

Voice Synthesis

Character Settings

Memory System

Build docs developers (and LLMs) love

Provider Types

Available Chat Providers

Cloud Providers

Router & Aggregator Providers

Local & Self-Hosted Providers

Regional & Specialized Providers

Speech Synthesis Providers

Commercial TTS Services

Open-Source & Local TTS

Transcription Providers

Provider Configuration Guide

Adding a Provider

Configuration Schema

Validation

Rate Limits & Quotas

Advanced Configuration

Custom Headers

Proxy Configuration

Multiple Provider Instances

Provider Capabilities

Troubleshooting

Provider Not Available

Connection Failed

Invalid API Key

Rate Limit Errors

Model Not Found

Code Reference

Related Resources