API Quickstart

Use the endpoint for your self-managed deployment with a router-issued caller token. The token authenticates the caller to GenAI Smart Router; provider keys stay server-side.

If you do not have a running router yet, start with Local Quickstart. From Getting Started, you might be looking for CLI guides: see Codex CLI or Claude Code CLI.

Replace https://<router-host> with your deployment URL. When these docs are served from a live router under /docs/, examples automatically use that router origin.

Environment

export ROUTER_BASE_URL="https://<router-host>"
export ROUTER_TOKEN="rtr_metrum_<user>_<project>_<env>_<key>_<secret>"
export ROUTER_MODEL="<allowed-model-group>"

Model group names are deployment-defined. If this hosted deployment exposes example names such as default, fast, small, medium, high, big-coder, or vision, treat them as deployment policy names, not product-required names.

Model Discovery

If you are not sure which ROUTER_MODEL value to use, call /v1/models with your router token first. The response is filtered by that token's allow list and returns the deployment-defined model groups you can request.

curl "$ROUTER_BASE_URL/v1/models" -H "Authorization: Bearer $ROUTER_TOKEN"

Use one returned id as the model value in chat, Responses, Messages, or CLI requests. If a caller token is limited to a smaller set of groups, other groups will not be listed and cannot be requested. See Available Models And Access for response examples and troubleshooting.

Successful output is a JSON list whose data[].id values are the model groups you may request.

OpenAI-Compatible Chat

curl "$ROUTER_BASE_URL/v1/chat/completions" -H "Authorization: Bearer $ROUTER_TOKEN" -H "Content-Type: application/json" -d '{
  "model": "'"$ROUTER_MODEL"'",
  "messages": [
    {"role": "user", "content": "Reply with exactly: router ok"}
  ]
}'

Successful output includes one assistant message with router ok.

OpenAI Responses

Use /v1/responses for Responses-compatible clients and agent frameworks.

curl "$ROUTER_BASE_URL/v1/responses" -H "Authorization: Bearer $ROUTER_TOKEN" -H "Content-Type: application/json" -d '{
  "model": "'"$ROUTER_MODEL"'",
  "input": "Reply with exactly: router ok",
  "max_output_tokens": 32
}'

Successful output includes text equivalent to router ok.

Anthropic-Compatible Messages

curl "$ROUTER_BASE_URL/anthropic/v1/messages" -H "Authorization: Bearer $ROUTER_TOKEN" -H "Content-Type: application/json" -d '{
  "model": "'"$ROUTER_MODEL"'",
  "max_tokens": 32,
  "messages": [
    {"role": "user", "content": "Reply with exactly: router ok"}
  ]
}'

Successful output includes one content block with router ok.

Image Input

Image requests use the same deployment-defined router model-group names. The router filters image-bearing requests to targets that have passed vision validation and advertise image in input_modalities.

The examples below use a realistic VLM response budget because image acceptance tests should not be judged with a tiny output cap. Use smaller caps only when explicitly testing cap enforcement.

OpenAI-compatible chat:

curl "$ROUTER_BASE_URL/v1/chat/completions" -H "Authorization: Bearer $ROUTER_TOKEN" -H "Content-Type: application/json" -d '{
  "model": "'"$ROUTER_MODEL"'",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "Read the receipt. Reply with only the merchant name."},
      {"type": "image_url", "image_url": {"url": "https://cdn.learnopencv.com/wp-content/uploads/2018/06/04100007/receipt.png"}}
    ]
  }],
  "max_tokens": 512,
  "stream": false
}'

OpenAI Responses:

curl "$ROUTER_BASE_URL/v1/responses" -H "Authorization: Bearer $ROUTER_TOKEN" -H "Content-Type: application/json" -d '{
  "model": "'"$ROUTER_MODEL"'",
  "input": [{
    "role": "user",
    "content": [
      {"type": "input_text", "text": "Read the receipt. Reply with only the merchant name."},
      {"type": "input_image", "image_url": "https://cdn.learnopencv.com/wp-content/uploads/2018/06/04100007/receipt.png"}
    ]
  }],
  "max_output_tokens": 512,
  "stream": false
}'

Anthropic-compatible Messages:

curl "$ROUTER_BASE_URL/anthropic/v1/messages" -H "Authorization: Bearer $ROUTER_TOKEN" -H "Content-Type: application/json" -d '{
  "model": "'"$ROUTER_MODEL"'",
  "max_tokens": 512,
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "Read the receipt. Reply with only the merchant name."},
      {"type": "image", "source": {"type": "url", "url": "https://cdn.learnopencv.com/wp-content/uploads/2018/06/04100007/receipt.png"}}
    ]
  }]
}'

Image-bearing requests bypass response caching. Usage logs include image count, image-token counts when the upstream reports them, calculated VLM cost, and upstream-reported billed cost when available.

For dedicated vision route configuration, pricing metadata, and CLI image smokes, see Image Analysis And VLM Routing.

Python Client

The router accepts OpenAI-compatible SDK traffic. This example creates an isolated uv project and calls the hosted router through /v1/chat/completions. Install uv first if it is not available in your shell.

mkdir smart-router-python-example
cd smart-router-python-example
uv init --bare
uv add openai

cat > smoke.py <<'PY'
import os
from openai import OpenAI

router_base_url = os.environ["ROUTER_BASE_URL"].rstrip("/")
router_token = os.environ["ROUTER_TOKEN"]
router_model = os.environ["ROUTER_MODEL"]

client = OpenAI(
  base_url=f"{router_base_url}/v1",
  api_key=router_token,
)

response = client.chat.completions.create(
  model=router_model,
  messages=[
      {"role": "user", "content": "Reply with exactly: router ok"},
  ],
  max_tokens=32,
)

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

export ROUTER_BASE_URL="https://<router-host>"
export ROUTER_TOKEN="rtr_metrum_<user>_<project>_<env>_<key>_<secret>"
export ROUTER_MODEL="<allowed-model-group>"
uv run python smoke.py

The same token and model-group rules apply to SDK calls: /v1/models shows only the groups that the token is allowed to use, and provider credentials remain server-side.

Common First-Run Issues

Symptom	Meaning	Next step
401 or 403 before model discovery	Token or endpoint mismatch	Confirm ROUTER_BASE_URL and ROUTER_TOKEN with the deployment administrator.
Expected group missing from /v1/models	The token allow list does not include that group	Use a listed group or request access.
403 model-not-allowed	Requested model group is not allowed for the token	Use one of the returned /v1/models IDs.
502 no-eligible-target for tools or images	The group is allowed but lacks a validated target for that request shape	Ask for a compatible group or target.
503 upstream-quota-exhausted	All eligible upstream providers reported exhausted balance, credits, quota, billing, or payment state	Retry after the administrator restores provider quota or include the request ID when escalating.
503 upstream-rate-limited	All eligible upstream providers were rate limited	Retry with backoff or include the request ID when escalating.
503 upstream-capacity-throttled	Provider/model/target shared shaping or adaptive backoff temporarily removed all otherwise eligible targets	Retry after the Retry-After window when present or include the request ID when escalating.
504 upstream-timeout	The selected upstream did not finish before timeout	Retry a smaller task or ask the administrator to inspect attempts.

See Error Reference for the full structured error list.