Get Started with the GreatRouter API

Getting started with GreatRouter takes less than 5 minutes. Head to the GreatRouter Dashboard and create a free account. You'll get a test API key immediately — no credit card required. Test keys have generous rate limits that are more than sufficient for development and prototyping. Once you have your API key, you can start making requests. The base URL is https://api.greatrouterai.com/v1. Every request requires an Authorization: Bearer YOUR_API_KEY header. That's it — one header, and you have access to over 150 AI models across text, image, video, music, and speech modalities. For production use, upgrade to a live API key from the dashboard. Live keys support higher rate limits, wallet-based billing (pay only for what you use), and access to all models including premium providers. The pricing is transparent — you see exactly what each request cost in the response metadata and in the dashboard logs. If you're integrating GreatRouter into an existing application that already uses the OpenAI SDK or REST API, the migration is trivial. Change the base URL from https://api.openai.com/v1 to https://api.greatrouterai.com/v1, swap your API key, and your existing code works unchanged. The router accepts standard OpenAI-format chat completion requests and returns OpenAI-format responses — plus routing metadata.

The simplest way to use GreatRouter is the auto-route endpoint. Send your prompt, and the router handles everything — classification, model selection, provider routing, and response normalization. Here's a minimal curl example:

curl -X POST https://api.greatrouterai.com/v1/auto/route \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Explain quantum computing in simple terms"}
    ]
  }'

In Python with the OpenAI SDK:

from openai import OpenAI

client = OpenAI(
    base_url="https://api.greatrouterai.com/v1",
    api_key="YOUR_API_KEY"
)

response = client.chat.completions.create(
    model="router",
    messages=[
        {"role": "user", "content": "Explain quantum computing in simple terms"}
    ]
)

print(response.choices[0].message.content)

In TypeScript/JavaScript:

const response = await fetch("https://api.greatrouterai.com/v1/auto/route", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    messages: [
      { role: "user", content: "Explain quantum computing in simple terms" }
    ]
  })
});

const data = await response.json();
console.log(data.output);
console.log("Routed to:", data.metadata.model);

The response includes not just the model output but also routing metadata: which model was selected, why it was selected, the task classification, and the cost of the request. This transparency helps you understand and trust the routing decisions.

While auto-route works great with zero configuration, you can provide hints to get even better results. The task parameter tells the router exactly what you want: "text_generation", "text_to_image", "text_to_video", "music_generation", "text_to_speech", or "automatic_speech_recognition". When you specify a task, the router skips classification and goes straight to model selection — faster and more deterministic. The capabilities parameter lets you request specific model features: "vision" for multimodal understanding, "function_calling" for tool use, "reasoning" for deep analytical tasks, "web_search" for real-time information, or "code_generation" for programming tasks. The router filters to models that support your requested capabilities. The optimization parameter controls the quality-cost trade-off. Set it to "quality" for the best available model regardless of cost (ideal for customer-facing features), "cost" for the cheapest model that meets minimum quality thresholds (ideal for background processing), or "balanced" (the default) for a middle ground that optimizes quality-per-dollar. Here's an example that combines these parameters for an image generation request with cost optimization:

curl -X POST https://api.greatrouterai.com/v1/auto/route \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "text_to_image",
    "optimization": "cost",
    "input": {
      "prompt": "A serene mountain lake at sunrise, photorealistic, 4K"
    }
  }'

The router will pick the cheapest image model that can produce a photorealistic result — likely Black Forest Labs' Flux Schnell at ~$0.004 per image — rather than the most expensive premium model.

Use the OpenAI SDK with base_url="https://api.greatrouterai.com/v1" for the fastest path to production — it works with Python, Node.js, and any OpenAI-compatible client. For auto-routing, call POST /v1/auto/route directly with fetch or curl.

import requests

result = requests.post(
    "https://api.greatrouterai.com/v1/auto/route",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "prompt": "Write a haiku about AI",
        "input": {"messages": [{"role": "user", "content": "Write a haiku about AI"}]},
        "optimization": "balanced"
    }
).json()
print(result["result"])
print("Model:", result.get("metadata", {}).get("model"))

For production deployments, configure routing preferences in the dashboard. Set your default optimization mode, exclude specific providers or models, and use budget_dollars on high-cost requests. These preferences apply automatically to all API requests from your account — no code changes needed. The dashboard also provides comprehensive observability: usage logs, cost analytics per model and task type, latency tracking, and error rate monitoring. You can see exactly where your inference budget is going and identify optimization opportunities. The same infrastructure powers GreatStudios and GreatChat — production applications built on GreatRouter's intelligent routing. For teams deploying at scale, GreatRouter supports multiple API keys per organization (for different services or environments) and usage partitioning by key from a single dashboard with unified billing and logging.