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#

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.

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

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

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

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

Provider comparison (video generation)#

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:

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

# 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):

# 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