Environment Variables for Providers#

All external providers are configured exclusively through a .env file. Copy the example and add only the keys you need—most capabilities have free or local fallbacks.

cp .env.example .env

Edit .env to include the relevant variables. The tool registry loads this file automatically on discovery.

Key variables and the capabilities they unlock:

# Free stock media (no cost, commercial use allowed)
PEXELS_API_KEY=your-key
PIXABAY_API_KEY=your-key
UNSPLASH_ACCESS_KEY=your-key

# Voice and images
ELEVENLABS_API_KEY=your-key
OPENAI_API_KEY=your-key
XAI_API_KEY=your-key
GOOGLE_API_KEY=your-key

# Multi-model image and video gateway
FAL_KEY=your-key

# Video providers
HEYGEN_API_KEY=your-key
RUNWAY_API_KEY=your-key

# Music
SUNO_API_KEY=your-key

# Mandarin TTS
DOUBAO_SPEECH_API_KEY=your-key
DOUBAO_SPEECH_VOICE_TYPE=zh_female_vv_uranus_bigtts

# Local GPU video generation (requires NVIDIA GPU + CUDA)
VIDEO_GEN_LOCAL_ENABLED=true
VIDEO_GEN_LOCAL_MODEL=wan2.1-1.3b

# Self-hosted options
MODAL_LTX2_ENDPOINT_URL=https://your-modal-endpoint
HF_TOKEN=your-token   # optional, for speaker diarization

Only add entries for providers you intend to use. The system treats missing keys as unavailable and routes to alternatives.

Local vs API Runtimes#

Tools declare a runtime in their contract: LOCAL, LOCAL_GPU, API, or HYBRID.

• LOCAL and LOCAL_GPU run entirely on your machine with no network calls or cost. Examples include Piper TTS, FFmpeg composition, and local diffusion or video models when VIDEO_GEN_LOCAL_ENABLED=true.
• API tools call cloud services and incur tracked costs. They require the corresponding environment variable.
• HYBRID tools (the selectors) can choose either path at runtime based on availability and scoring.

Local paths remain functional even with zero API keys. Enable GPU support with make install-gpu followed by the two environment variables above. Local models are selected via VIDEO_GEN_LOCAL_MODEL (examples: wan2.1-1.3b, wan2.1-14b, hunyuan-1.5, ltx2-local, cogvideo-5b).

Selector Pattern#

Three selector tools abstract families of providers:

• tts_selector routes among elevenlabs_tts, google_tts, openai_tts, piper_tts, and doubao_tts.
• image_selector routes among flux_image, grok_image, google_imagen, openai_image, recraft_image, and stock tools.
• video_selector routes among kling_video, veo_video, heygen_video, runway_video, local variants, and stock video tools.

Selectors first honor an explicit preferred_provider when supplied. They then rank available tools using task fit, output quality, control, reliability, cost, latency, and continuity. Input schemas are adapted transparently (for example, prompt versus query). Adding a new provider tool automatically makes it visible to the matching selector—no code changes required.

See Provider Selection for the full scoring rules and delivery-promise enforcement.

Preflight Reporting#

Run preflight before any production to see exactly what is configured.

make preflight

Or invoke the registry directly:

python -c "
from tools.tool_registry import registry
import json
registry.discover()
print(json.dumps(registry.provider_menu_summary(), indent=2))
"

The summary includes:

• composition_runtimes (ffmpeg, remotion, hyperframes)
• capabilities with configured / total counts and provider lists per capability
• setup_offers (short env-var fixes)
• runtime_warnings

Use the output to decide which providers to add or which local fallbacks are active. See Preflight Diagnostics for interpreting warnings.

HTTP and SDK Invocation Patterns#

Provider tools call domain-specific endpoints or SDKs directly. The agent never invokes general-purpose LLM APIs at runtime.

Most tools use the requests library for HTTP calls. Some providers require reference-image uploads before generation. Async jobs use provider-specific polling loops. Local tools use libraries such as diffusers pipelines when GPU mode is enabled.

All paid calls go through cost estimation, reservation, and reconciliation before execution. Results (including cost and artifacts) are recorded in checkpoints and decision logs.

For per-provider setup steps, pricing, and free-tier details, see the Provider Guide. For the full tool contract and discovery mechanics, see Tool Registry.