Quickstart

هذا المحتوى غير متوفر بلغتك بعد.

Auto routing

curl https://api.greatrouterai.com/v1/auto/route \
  -H "Authorization: Bearer $GREAT_ROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Hello!",
    "input": {
      "messages": [{"role": "user", "content": "Hello!"}]
    }
  }'

Image generation

curl https://api.greatrouterai.com/v1/auto/route \
  -H "Authorization: Bearer $GREAT_ROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Generate an image of a serene mountain lake at sunset",
    "task": "image",
    "content_mode": "generate",
    "input": {
      "messages": [{"role": "user", "content": "Generate an image of a serene mountain lake at sunset"}]
    }
  }'

The router automatically selects the cheapest capable image model. You can also set task: "image" to explicitly route to image models.

Cost-constrained routing

Set a maximum cost in USD to avoid surprises:

curl https://api.greatrouterai.com/v1/auto/route \
  -H "Authorization: Bearer $GREAT_ROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Write a 500-word blog post about AI",
    "budget_dollars": 0.01,
    "input": {
      "messages": [{"role": "user", "content": "Write a 500-word blog post about AI"}]
    }
  }'

budget_dollars is the maximum estimated cost in USD. Models exceeding this budget are automatically excluded.

You can also use maxCost for tier-based filtering on the explicit route:

curl https://api.greatrouterai.com/v1/models/route \
  -H "Authorization: Bearer $GREAT_ROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Write a 500-word blog post about AI",
    "maxCost": "economy",
    "filter": {"task_type": "text_generation"},
    "input": {
      "messages": [{"role": "user", "content": "Write a 500-word blog post about AI"}]
    }
  }'

maxCost accepts price tiers: economy, standard, balanced, premium, flagship.

Video generation

curl https://api.greatrouterai.com/v1/auto/route \
  -H "Authorization: Bearer $GREAT_ROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A cat walking on a tightrope",
    "task": "video",
    "content_mode": "generate",
    "input": {
      "messages": [{"role": "user", "content": "A cat walking on a tightrope"}]
    }
  }'

Speech-to-text

curl https://api.greatrouterai.com/v1/auto/route \
  -H "Authorization: Bearer $GREAT_ROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Transcribe this audio",
    "task": "speech",
    "content_mode": "generate",
    "input": {
      "messages": [{
        "role": "user",
        "content": [{"type": "audio_url", "audio_url": {"url": "https://example.com/audio.mp3"}}]
      }]
    }
  }'

Catalog browse (taxonomy & model lines)

List taxonomy branches and paginated model lines (public, no auth):

curl https://api.greatrouterai.com/v1/catalog/taxonomy
curl 'https://api.greatrouterai.com/v1/catalog/families?taxonomy=llm&routable_only=true&limit=12'

Query models with filters:

curl https://api.greatrouterai.com/v1/models/query \
  -H "Content-Type: application/json" \
  -d '{"category": "llm", "price_tier": "economy", "routable_only": true, "limit": 20}'

Music generation

curl https://api.greatrouterai.com/v1/auto/route \
  -H "Authorization: Bearer $GREAT_ROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Compose an upbeat electronic dance track",
    "task": "music",
    "content_mode": "generate",
    "input": {
      "messages": [{"role": "user", "content": "Compose an upbeat electronic dance track"}]
    }
  }'

Error handling

HTTP Code	Meaning
`400`	Bad request — check your JSON payload and required fields
`401`	Unauthorized — invalid or missing API key
`404`	Model not found — check the model ID
`429`	Rate limited — slow down your requests
`500`	Internal error — contact support if persistent

Client SDKs

GreatRouter provides official SDKs for TypeScript and Python, or use any HTTP client with the REST API.

Base URL: https://api.greatrouterai.com/v1

TypeScript

npm install @greatrouter/sdk

import { GreatRouter } from '@greatrouter/sdk'

const client = new GreatRouter('pk_live_...')

// Auto route
const result = await client.autoRoute({
  prompt: 'Hello!',
  input: { messages: [{ role: 'user', content: 'Hello!' }] },
})

// Get suggestions without inference
const suggestions = await client.autoSuggest({ prompt: 'Hello!', task: 'text' })

// Budget-constrained routing
const cheap = await client.autoRoute({
  prompt: 'Write a haiku',
  input: { messages: [{ role: 'user', content: 'Write a haiku' }] },
  budget_dollars: 0.01,
})

Python

pip install greatrouter

from greatrouter import GreatRouter

client = GreatRouter("pk_live_...")

# Auto route
result = client.auto_route({
    "prompt": "Hello!",
    "input": {"messages": [{"role": "user", "content": "Hello!"}]},
})

# Get suggestions without inference
suggestions = client.auto_suggest({"prompt": "Hello!", "task": "text"})

# Budget-constrained routing
cheap = client.auto_route({
    "prompt": "Write a haiku",
    "input": {"messages": [{"role": "user", "content": "Write a haiku"}]},
    "budget_dollars": 0.01,
})

For async usage:

from greatrouter import AsyncGreatRouter

async with AsyncGreatRouter("pk_live_...") as client:
    result = await client.auto_route({...})

Direct HTTP

Use any HTTP client. The API accepts Content-Type: application/json with Authorization: Bearer <key>.

curl https://api.greatrouterai.com/v1/auto/route \
  -H "Authorization: Bearer $GREATROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hello!", "input": {"messages": [{"role": "user", "content": "Hello!"}]}}'