# Providers

A provider is an upstream API service that executes tool skills — generating images, creating videos, upscaling media, etc. ToolRouter supports multiple providers for the same capability, letting agents choose the best option for their use case.

## Active providers

| Provider | Capabilities | Pricing model |
|----------|-------------|---------------|
| **fal.ai** | Image gen (50+ models), video gen (12 models), upscale, background removal | Live pricing API (pre-execution) |
| **Prodia** | Image gen (10+ models + dynamic), video gen (7 models + dynamic), upscale, background removal | Live pricing API (post-execution via `?price=true`) |
| **Higgsfield** | Image gen (Soul model — realistic UGC photos) | Fixed credit rates ($1 = 16 credits) |
| **Photalabs** | Image gen, editing, enhancement with identity preservation | Fixed per-image ($0.09 at 1K, $0.18 at 4K) |
| **ElevenLabs** | Voice generation, sound effects, music, transcription, dubbing | Per-character / per-second |
| **Serper** | Web search | Per query |
| **Exa** | Neural search (lead finder) | Per query |
| **Firecrawl** | Web scraping / crawling | Per page |
| **Parallel AI** | Deep research | Per research task |
| **ScrapeCreators** | Social media data extraction | Per request |

## How agents pick a provider

Agents choose a provider **by selecting a model**. Each model key routes to a specific provider automatically:

```
model: "flux-pro"           → fal.ai
model: "prodia-flux-2-pro"  → Prodia
model: "soul"               → Higgsfield
model: "phota"              → Photalabs
```

For image and video tools, there are three ways to route to a provider:

### 1. Registry model key (recommended)

Use a curated model key from the registry. Run `list_models` to see all options with descriptions, capabilities, and provider info.

```json
{ "tool": "generate-image", "skill": "text_to_image", "input": { "prompt": "a sunset", "model": "prodia-recraft-v4" } }
```

### 2. Dynamic Prodia job type

Pass any Prodia job type directly — no need for it to be in our registry. Anything starting with `inference.` routes to Prodia automatically.

```json
{ "tool": "generate-image", "skill": "text_to_image", "input": { "prompt": "a sunset", "model": "inference.flux-2.pro.txt2img.v1" } }
```

This supports all 100+ Prodia models, including new ones added after our registry was last updated.

### 3. Dynamic fal.ai model ID

Pass any fal.ai model endpoint ID directly. Anything starting with `fal-ai/` routes to fal.ai.

```json
{ "tool": "generate-image", "skill": "text_to_image", "input": { "prompt": "a sunset", "model": "fal-ai/flux-pro/v1.1" } }
```

## Provider comparison (image generation)

Models available on multiple providers with verified live pricing:

| Model | fal.ai | Prodia | Notes |
|-------|--------|--------|-------|
| Flux Schnell | $0.003/MP | $0.0025/img | Prodia slightly cheaper |
| Flux Dev | $0.025/MP | $0.020/img | Prodia ~20% cheaper |
| Flux Pro 1.1 | $0.040/MP | $0.040/img | Same price |
| Flux 2 Dev | $0.012/MP | $0.012/img | Same price |
| Flux 2 Pro | $0.030/MP | $0.030/img | Same price |
| Flux Kontext Pro | $0.040/img | $0.040/img | Same price |
| Recraft V4 | $0.250/img | $0.040/img | Prodia 84% cheaper |
| SDXL | $0.065/MP | $0.002/img | Prodia 97% cheaper |
| Gemini 3 Pro | $0.080/img | $0.150/img | fal.ai 47% cheaper |

*fal.ai per-megapixel prices calculated at 1MP (1024×1024). Prodia prices are flat per-image regardless of resolution.*

## Provider comparison (video generation)

| Model | fal.ai | Prodia | Notes |
|-------|--------|--------|-------|
| Wan 2.2 Lightning | $0.05/s (~$0.25/5s) | $0.09 flat | Prodia cheaper, ~23s generation |
| Kling 3.0 | $0.10/s (~$0.50/5s) | live pricing | — |
| Veo 3.1 Fast | $0.10/s (~$0.60/6s) | live pricing | — |
| Sora 2 | $0.50/s (~$2.50/5s) | live pricing | — |

## How pricing works per provider

### fal.ai
- **Pre-execution pricing**: `GET /v1/models/pricing` returns per-model rates before running a job
- **Unit types**: per-megapixel (scales with resolution) or per-image (flat)
- **Live model discovery**: `GET /v1/models` returns the full catalog with metadata

### Prodia
- **Post-execution pricing**: `?price=true` query param on the job request returns the actual cost in the response
- **Flat per-image/video**: cost doesn't change with resolution for most models
- **No model listing API**: models are hardcoded in our registry or passed as dynamic `inference.*` job types
- **No pre-execution pricing**: cost is only known after the job completes

### Higgsfield
- **Fixed credit rates**: $1 = 16 credits, Soul 720p = 1.5 credits ($0.09), 1080p = 3 credits ($0.19)
- **No pricing API**: rates are hardcoded from their documentation
- **No model listing API**: model IDs are hardcoded

### Photalabs
- **Synchronous JSON API**: POST with prompt, get base64 PNG images back — no polling
- **Fixed per-image pricing**: $0.09 at 1K resolution, $0.18 at 4K
- **Identity profiles**: trained on 30-50 reference photos, referenced via `[[profile_id]]` in prompts
- **Three endpoints**: generate (text-to-image), edit (image editing), enhance (quality improvement)

## BYOK (Bring Your Own Key)

You can use your own provider API keys instead of the platform defaults. With BYOK, provider charges go to your account directly and ToolRouter only meters the 5% platform fee.

**Per-request header:**
```bash
curl -X POST https://api.toolrouter.com/v1/tools/call \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "X-Provider-Key-fal: <YOUR_FAL_KEY>" \
  -d '{"tool":"generate-image","skill":"text_to_image","input":{"prompt":"a sunset"}}'
```

**Saved credentials** (persists across calls):
```bash
# Via MCP
save_credential({ name: "fal", value: "your-fal-key" })

# Via REST
POST /v1/credentials { "name": "fal", "value": "your-fal-key" }
```

Resolution order: per-request header → saved credential → platform default.

## Circuit breakers

Each provider has a circuit breaker that tracks health:

- **Closed** (healthy) — calls route normally
- **Open** (unhealthy) — provider excluded after 3 consecutive failures
- **Half-open** — test call allowed after 60 seconds to check recovery

When a provider's circuit breaker trips, calls to models on that provider will fail fast with a clear error rather than timing out.

## API endpoints

Two public endpoints expose provider information (no auth required):

```bash
# List all providers with metadata
curl https://api.toolrouter.com/v1/providers

# Provider detail with tools powered
curl https://api.toolrouter.com/v1/providers/prodia
```