Skip to content

Quickstart

This page walks a brand-new user from "I have an API key" to a working first request in five minutes. All examples use environment variables so that no real credential is ever committed to source control.

1. Get a gateway key

You need a SMART_GATEWAY_API_KEY. The key is distinct from your OpenRouter key. Ask the operator to issue one, or rotate one yourself following the procedure in docs-internal/operations/secret-rotation.md if you already have shell access to the production host.

The key is sent as a standard Authorization: Bearer … header on every request, exactly like an OpenAI key.

2. Set two environment variables

export SMART_GATEWAY_API_KEY="<your-gateway-key>"
export SMART_GATEWAY_BASE_URL="https://smart-openrounter.bee1x.one"

All examples below assume these are set.

3. Make a first request (smart-router)

curl -sS "$SMART_GATEWAY_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $SMART_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "smart-router",
        "messages": [{"role": "user", "content": "Reply with the single word PONG and nothing else."}],
        "max_tokens": 8
      }'

Expected response (truncated):

{
  "id": "gen-1787490793-…",
  "object": "chat.completion",
  "model": "deepseek/deepseek-v4-flash-0731",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "PONG"},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 17, "completion_tokens": 1, "total_tokens": 18}
}

The model field echoes the real OpenRouter ID, not the alias you sent. That is intentional: clients can use it for logging, but should not hard-code it.

4. Force a specific tier

The same request body with a different model field pins the routing decision:

Request model What happens
smart-router Default. Gateway chooses Flash, Pro, or Scout per policy.
smart-router-flash Always DeepSeek V4 Flash.
smart-router-pro Always DeepSeek V4 Pro.
smart-router-free Always Nemotron 3 Ultra. Rejected (HTTP 403) if the request is marked sensitive. 
curl -sS "$SMART_GATEWAY_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $SMART_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "smart-router-pro",
        "messages": [{"role": "user", "content": "Outline three ways to invalidate a JWT."}],
        "max_tokens": 200
      }'

5. Streaming

Set "stream": true to receive a Server-Sent Events response. Each event is a partial chat completion chunk in OpenAI's standard SSE shape:

curl -sN "$SMART_GATEWAY_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $SMART_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "smart-router-flash",
        "stream": true,
        "messages": [{"role": "user", "content": "Count to 5 slowly."}],
        "max_tokens": 64
      }'

The gateway performs a small amount of normalization on streaming chunks: when a model emits a reasoning-only delta (DeepSeek extended thinking), the gateway folds the reasoning text into a content delta so that OpenAI-compatible clients do not see an "empty" final chunk. See User guide → Streaming for the exact behavior and a list of clients known to be affected.

6. Common errors

HTTP Body What it means
200 {"choices":[…]} Success.
401 {"detail":"Not authenticated"} Missing or malformed Authorization header.
403 {"detail":"A force-free request that violates privacy policy must fail closed."} You sent smart-router-free (or forced a free model in any other way) on a request marked sensitive: true. Drop the override, or set sensitive: false deliberately.
403 {"detail":"Scout cannot be called on sensitive data."} A header (X-Scout: true) tried to enable Scout on a sensitive task.
500 {"detail":"OpenRouter API error: …"} Upstream failure. The gateway may already have fallen back to GLM-5.2 if the failing call was for Pro.
502 / 503 / 504 {"detail":"OpenRouter connection failed: …"} Network/transport error after exhausting retries.

The full error matrix is in API reference → Errors and Troubleshooting.

7. Wire it into a client

Pick the integration guide for your client:

You now have a working setup. To go deeper: