Skip to main content
To maximize efficiency and cost savings, LLM Router requires you to define strict rules about which models handle specific types of workloads. Instead of hardcoding a single model for every request in your application, you define Tags. For example, you can configure your router so that all UI Design questions go to Gemini, but all Unit Testing questions go to DeepSeek. You achieve this powerful dynamic routing using the gateway.tags configuration.

​
How Tag Routing Works

When a request arrives, our internal Gateway AI analyzes the prompt in milliseconds. It performs two critical steps:
  1. Intent Matching: It matches the user’s prompt to the description of one of your provided tags.
  2. Complexity Scoring: It scores the difficulty of the prompt (from 0.0 to 1.0) and selects the appropriate model from that tag’s models array.

​
Critical Rule: Sorting Your Models

When defining the models array inside a tag, you must sort the models from most complex (smartest/most expensive) to least complex (simplest/cheapest). The Gateway uses the complexity score to pick the right model from this list:
  • A score of 0.9 (Very Hard) will select the first model in your array.
  • A score of 0.1 (Very Simple) will select the last model in your array.

​
Basic Implementation

You pass the gateway object directly into your request.
TypeScript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.llmrouter.app/v1",
  apiKey: process.env.LLM_ROUTER_API_KEY,
});

async function main() {
  const response = await client.chat.completions.create({
    // Notice we do NOT specify a hardcoded `model` here.
    // The router will pick one based on the matched tag.
    messages: [
      { role: "user", content: "Write a Jest unit test for my React button." },
    ],

    // @ts-expect-error - Custom LLM Router extension
    gateway: {
      tags: [
        {
          name: "coding",
          description:
            "Code generation, refactoring, debugging, and software development",
          models: [
            "anthropic/claude-3-5-sonnet", // Complex (Score: 0.8+)
            "openai/gpt-5.4", // Medium (Score: 0.4 - 0.7)
            "deepseek/deepseek-chat", // Simple (Score: < 0.4)
          ],
        },
        {
          name: "testing",
          description:
            "Writing unit tests, integration tests, test-driven development, and QA",
          models: [
            "openai/gpt-5.4", // Complex
            "deepseek/deepseek-chat", // Medium
            "mistral/mistral-large-latest", // Simple
          ],
        },
      ],
      // Fallback specifically for Multi-Modal / Image requests
      imageGenerationModel: "black-forest-labs/flux-1.1-pro",
    },
  });

  console.log(response.choices[0].message.content);
}
main();

​
What happens in this example?

  1. Analysis: The user asked for a “Jest unit test”.
  2. Intent Matching: The Gateway matches the intent perfectly to the "testing" tag.
  3. Complexity Scoring: The Gateway determines that writing a basic React button test is moderately difficult (Score: 0.5).
  4. Execution: Because the score is in the middle, it selects the middle model from the "testing" array: deepseek/deepseek-chat. (Saving you the cost of GPT-5.4).

​
Configuring Multi-Modal Fallbacks

Sometimes, a user’s prompt will trigger a completely different modality. For example, if your app is a general chatbot, a user might suddenly ask: “Generate an image of a sunset.” If the Gateway detects that the user’s intent is to create a visual asset (not text), it will ignore your text-based tags and instantly route the request to the model specified in imageGenerationModel. 
gateway: {
  // Used exclusively when the request involves creating images.
  imageGenerationModel: "google/gemini-3-pro-image",
}

​
Configuration Properties

​
The Tag Object

PropertyTypeDescription
namestringA short identifier for the tag (e.g., “coding”, “support”).
descriptionstringCrucial: A clear, semantic description of the topics this tag covers. The internal AI uses this string to match the user’s prompt.
modelsstring[]An array of models sorted from Most Complex to Least Complex. The router picks the model based on the prompt’s difficulty score.

​
The Gateway Object

PropertyTypeDescription
tagsTag[]An array of custom routing rules.
imageGenerationModelstring(Optional) The specific model to use if the Gateway determines the user wants to generate an image instead of text.