Smart Router — Intelligent Model Router

Route tasks to the best model automatically, via any OpenAI-compatible API.

Author: [email protected]

Setup

Models and provider are configured in models.json. Set two environment variables:

• SMART_ROUTER_BASE_URL — OpenAI-compatible API base URL (e.g. https://api.openai.com/v1)
• SMART_ROUTER_API_KEY — API key for the provider

Edit models.json to customize categories, models, and defaults for your provider.

@ Alias Shortcuts

Prefix a message with @alias to skip auto-classification and call a specific model directly.

Format: @alias your question or prompt here

Alias Table

Alias	Model ID	Category
Vision
@gpt4o	chatgpt-4o-latest	vision
@qwen-vl	qwen3-vl-235b-a22b-instruct	vision
@qwen-vl-max	qwen-vl-max-2025-08-13	vision
@llama-vl	llama-3.2-90b-vision-instruct	vision
@qwen-vl-32b	qwen3-vl-32b-instruct	vision
Image Gen
@imagen	google/imagen-4-ultra	image_gen
@flux	black-forest-labs/flux-1.1-pro-ultra	image_gen
@flux-kontext	black-forest-labs/flux-kontext-max	image_gen
@dalle	dall-e-3	image_gen
@flux2	flux-2-pro	image_gen
Video Gen
@sora	sora-2-pro-all	video_gen
@veo	veo3.1-pro-4k	video_gen
@vidu	viduq3-pro	video_gen
@kling	kling-video	video_gen
@runway	runwayml-gen4_turbo-10	video_gen
Audio
@suno	suno_music	audio
@tts	gemini-2.5-pro-preview-tts	audio
@tts-hd	tts-1-hd	audio
@kling-audio	kling-audio	audio
@vidu-tts	vidu-tts	audio
Reasoning
@o3	o3	reasoning
@o3-pro	o3-pro	reasoning
@o4-mini	o4-mini	reasoning
@deepseek	deepseek-r1	reasoning
@gemini-think	gemini-2.5-pro-thinking	reasoning
@claude-think	claude-sonnet-4-5-20250929-thinking	reasoning
Code
@claude	claude-opus-4-6	code
@codex	gpt-5.1-codex-max	code
@claude-sonnet	claude-sonnet-4-6	code
@qwen-coder	qwen3-coder-480b-a35b-instruct	code
@qwen-coder-plus	qwen3-coder-plus	code
@gpt4t	gpt-4-turbo	code
General
@gpt52 / @gpt5	gpt-5.2-chat-latest	general
@gemini	gemini-2.5-pro	general
@deepseekv3	deepseek-v3.2	general
@qwen	qwen3-max	general
@claude-chat	claude-opus-4-6	general

Aliases are case-insensitive. If no alias matches, attempt fuzzy match on model name/ID. If still no match, prompt the user.

Auto-Classification Rules

When no @alias is specified, classify the task automatically:

Category	Trigger
vision	User sends image/URL, asks to analyze, describe, OCR, understand image content
image_gen	Requests to draw, generate image, design poster, create illustration
video_gen	Requests to generate video, animation, text-to-video, image-to-video
audio	Requests for music generation, TTS, sound effects
reasoning	Complex math, logic puzzles, proofs, deep analysis, long-chain reasoning
code	Code generation, debugging, refactoring, review (when external model needed)
general	Everyday chat, translation, summarization, writing, Q&A

Usage

1. Read Model Config

cat "$(dirname "$0")/../models.json"

2. Select Model

• Determine category based on classification rules above
• Use the first model with "default": true in each category
• If user specifies a model via @alias, use that model directly
• For cost-sensitive tasks, pick a smaller model in the same category

3. Call Model

Chat (vision / reasoning / code / general)

scripts/call-model.sh --model "MODEL_ID" --prompt "user request" --type chat

With image (vision):

scripts/call-model.sh --model "MODEL_ID" --prompt "request" --type chat --image "IMAGE_URL"

Image Generation

scripts/call-model.sh --model "MODEL_ID" --prompt "image description" --type image

Async Tasks (video / audio)

scripts/call-model.sh --model "MODEL_ID" --prompt "task description" --type async

TTS

scripts/call-model.sh --model "MODEL_ID" --prompt "text to speak" --type tts --voice alloy

4. Return Results

• Chat: return the model's text reply directly
• Image: return the generated image URL in markdown format
• Video/Audio: return task status and result URL

Model Recommendations

• Vision: qwen3-vl-235b-a22b-instruct (strongest visual understanding)
• Image gen: google/imagen-4-ultra (highest quality)
• Video: sora-2-pro-all (best results)
• Music: suno_music / TTS: tts-1-hd or gemini-2.5-pro-preview-tts
• Reasoning: o3 (strongest reasoning)
• Code: gpt-5.1-codex-max
• General: claude-opus-4-6

Fallback

If a model call fails, automatically fall back to the next model in the same category.

Customization

Edit models.json to: - Add/remove models in any category - Change default models - Add new categories - Update aliases in SKILL.md to match

The scripts/sync-models.sh script lists all available models from your provider to help discover new ones.