Smart Router

Set the model field to a router alias instead of a specific model ID. Smart Router analyses your request and selects the optimal upstream model automatically — no code changes needed when new models are added.

Router aliases

Every alias is a full model ID. There are exactly nine:

Alias	Behaviour
auto	Best available model for the request, balancing capability, latency, and cost
auto/free	Free-tier models only — zero token cost
auto/eco	Cheapest paid model that can handle the task
auto/premium	Highest-capability model available
auto/search	Web search with an AI summary and citations
auto/image	Best image generation model
auto/video	Best video generation model
auto/tts	Best text-to-speech model
auto/music	Best music generation model

The auto/ prefix is required

free, eco, premium, search, image, video, tts and music are not valid model IDs on their own — sending one returns an invalid-model error. Always write auto/free, auto/eco, and so on.

auto

Smart Router picks the best available model for each request based on capability, latency, and cost.

response = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Hello!"}]
)

Routing also considers prompt complexity: prompts are scored and bucketed into tiers (simple, medium, complex, reasoning, coding, creative), and each tier maps to its own model shortlist per profile.

auto/free

Routes exclusively to free-tier models. Zero token cost — great for development and experimentation.

response = client.chat.completions.create(
    model="auto/free",
    messages=[{"role": "user", "content": "Hello!"}]
)

auto/eco

Selects the most cost-efficient paid model that can handle the task. Minimises spend per token.

response = client.chat.completions.create(
    model="auto/eco",
    messages=[{"role": "user", "content": "Hello!"}]
)

auto/premium

Routes to the highest-capability model available. Best for complex reasoning and production workloads.

response = client.chat.completions.create(
    model="auto/premium",
    messages=[{"role": "user", "content": "Hello!"}]
)

auto/search

Web search with AI-generated summary and source citations. Uses the chat completions endpoint but returns a custom response format (not standard OpenAI choices array).

Request

import requests

resp = requests.post("https://api.jarvisclaw.ai/v1/chat/completions",
    headers={"Authorization": "Bearer sk-your-api-key", "Content-Type": "application/json"},
    json={
        "model": "auto/search",
        "messages": [{"role": "user", "content": "What is retrieval augmented generation?"}]
    })
data = resp.json()

Response

Non-standard format

auto/search does NOT return the OpenAI-compatible {"choices": [{"message": ...}]} format. It returns a custom search response with summary, sources_used, and inline citation links.

{
  "query": "What is retrieval augmented generation?",
  "summary": "Retrieval Augmented Generation (RAG) is a technique that...[1](https://example.com)...",
  "citations": [],
  "sources_used": 10,
  "model": "auto/search"
}

The model field reports whichever upstream the router picked for synthesis, so treat it as informational — it changes as the routing table changes.

Field	Type	Description
query	string	The original query
summary	string	AI-generated answer with inline [N](url) citation links
citations	array	Reserved (currently empty — citations are inline in summary)
sources_used	integer	Number of web sources consulted
model	string	The upstream model used for synthesis

Example

import requests

resp = requests.post("https://api.jarvisclaw.ai/v1/chat/completions",
    headers={"Authorization": "Bearer sk-your-api-key", "Content-Type": "application/json"},
    json={
        "model": "auto/search",
        "messages": [{"role": "user", "content": "latest AI agent frameworks 2026"}]
    })

data = resp.json()
print(data["summary"])
print(f"Sources consulted: {data['sources_used']}")

auto/image

Routes to the best available image generation model. See Image Generation API for full documentation.

import requests

resp = requests.post("https://api.jarvisclaw.ai/v1/images/generations",
    headers={"Authorization": "Bearer sk-your-api-key", "Content-Type": "application/json"},
    json={"model": "auto/image", "prompt": "A cat on Mars", "size": "1024x1024"})

auto/tts

Routes to the best available text-to-speech model. See Audio API for full documentation.

x402 wallet callers

Smart-route TTS has failed to settle for direct-wallet (private_key) callers in testing. Pass an explicit model such as elevenlabs/flash-v2.5 when paying from your own wallet.

import requests

resp = requests.post("https://api.jarvisclaw.ai/v1/audio/speech",
    headers={"Authorization": "Bearer sk-your-api-key", "Content-Type": "application/json"},
    json={"model": "auto/tts", "input": "Hello world!", "voice": "sarah"})

auto/music

Routes to the best available music generation model. See Music Generation API for full documentation.

import requests

resp = requests.post("https://api.jarvisclaw.ai/v1/audio/generations",
    headers={"Authorization": "Bearer sk-your-api-key", "Content-Type": "application/json"},
    json={"model": "auto/music", "prompt": "Chill lo-fi beat", "instrumental": True})

auto/video

Routes to the best available video generation model. See Video Generation API for full documentation.

Duration constraints

auto/video may route to azure/sora-2 which only supports durations of 4, 8, or 12 seconds. Do not pass duration_seconds: 5 — use 4 instead.

import requests

resp = requests.post("https://api.jarvisclaw.ai/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key", "Content-Type": "application/json"},
    json={"model": "auto/video", "prompt": "Ocean waves at sunset", "duration_seconds": 4})