API reference

Quickstart

1. 1. Create a key

   Issue one from the dashboard. The full key is shown once, at creation. Only a sha256 of it is stored, so a lost key has to be revoked and replaced rather than recovered.

2. 2. Point your client at Eaon

   Two environment variables. No SDK to install and no proxy to run.

   export EAON_API_KEY="eaon_sk_..."
   export OPENAI_BASE_URL="https://ai.eaon.dev/v1"
   export OPENAI_API_KEY="$EAON_API_KEY"

3. 3. Send a request

   eaon/auto picks the cheapest model that can serve the request. Name a model directly to override it.

   curl https://ai.eaon.dev/v1/chat/completions \
     -H "Authorization: Bearer $EAON_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "model": "eaon/auto",
       "messages": [{"role": "user", "content": "ping"}]
     }'

Editors and SDKs

Anything that speaks the OpenAI protocol works. These are the settings for the clients people ask about most.

export ANTHROPIC_BASE_URL="http://localhost:3000/v1"
export ANTHROPIC_AUTH_TOKEN="eaon_sk_..."
export ANTHROPIC_MODEL="eaon/sonnet-5"

claude

Usage and limits

Every plan is a grant of real upstream spend, not a token allowance. A call costs what it actually costs to serve, and the grant refills on its reset date. Paid plans reset weekly; Free resets monthly.

• Budget is reserved before the upstream call and reconciled to the real cost once the response is in hand, so a burst of parallel requests cannot overspend it.
• A failed upstream call is refunded. You are not charged for a response you did not get.
• Running out returns 402 until the usage grant resets or you move up a plan. Requests are also capped at 300 a minute per IP address, shared across every key; going over returns 429 with a Retry-After header.

Authentication

Send your key as a bearer token. Keys are created in the dashboard and shown once, so store it when you make it.

Authorization: Bearer eaon_sk_1f4c...

POST /v1/chat/completions

The request and response bodies are the OpenAI ones. Extra fields you send are forwarded upstream untouched.

curl http://localhost:3000/v1/chat/completions \
  -H "Authorization: Bearer $EAON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "eaon/sonnet-5",
    "temperature": 0.4,
    "messages": [
      {"role": "system", "content": "You are terse."},
      {"role": "user", "content": "Why is my build 40 seconds slower?"}
    ]
  }'

Streaming

Set stream: true for server-sent events. Frames are passed through byte for byte, ending with data: [DONE].

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:3000/v1",
    api_key=os.environ["EAON_API_KEY"],
)

with client.chat.completions.stream(
    model="eaon/gemini-3.8-flash",
    messages=[{"role": "user", "content": "Summarise this diff."}],
) as stream:
    for event in stream:
        if event.type == "content.delta":
            print(event.delta, end="", flush=True)

GET /v1/models

Returns only the models your plan can call, plus your account’s usage grant. There is no per-model rate or remaining-calls figure here — real cost depends on prompt and reply length, so the only exact number is what the whole account has left. budget_period_days is how often that grant resets — 7 for every paid plan, 30 on Free.

{
  "object": "list",
  "account": {
    "plan": "plus",
    "usage_multiplier": 5,
    "api_credit_monthly_usd": { "low": 165, "high": 430 },
    "budget_usd": 37.5,
    "budget_period_days": 7,
    "spent_usd": 12.184219,
    "remaining_usd": 25.315781
  },
  "data": [
    {
      "id": "eaon/sonnet-5",
      "object": "model",
      "owned_by": "anthropic",
      "context_window": 1000000,
      "eaon": { "cost_tier": "standard", "max_output_tokens": 16000 }
    }
  ]
}

Model ids

Tier is a relative cost band: flash, standard, or frontier. Billing is always real tokens.

Auto-routing

Send model: "eaon/auto" and the gateway picks a model per request instead of you naming one. It looks at the conversation for signals — code, multi-step reasoning, how much context it needs — then prices every model your plan can call for a call that size, the same way it bills, and uses whichever is cheapest and still capable. A short message with no special demands lands on the cheapest model available; a pasted stack trace or an “optimize this algorithm” ask moves to one tagged for it. It only ever picks from models your plan already grants — it routes within that set, it does not unlock a new one.

The response always reports the model that actually ran it, in the body’s model field and the x-eaon-model header, plus an x-eaon-routed-from header naming that it was auto-routed.

x-eaon-model:        eaon/gemini-3.8-flash
x-eaon-routed-from:  eaon/auto
x-eaon-cost-usd:     0.000041

Metering headers

A non-streaming response carries what it actually cost. A streamed one does not — that cost is only known once the response finishes, after the headers have already gone out — so track spend for those from GET /v1/models or the dashboard instead.

x-eaon-model:    eaon/sonnet-5
x-eaon-cost-usd: 0.014820
x-eaon-upstream: live

Errors

Errors use the OpenAI envelope. A call reserves its worst-case cost against your budget before it reaches a model; if it then fails upstream, that reservation is refunded in full, so a failed call is never actually charged.

GET /v1/health

An unauthenticated liveness check, for uptime monitors and load balancers. It reports whether the gateway is up, not whether any particular model is. The status page answers the second question, measured from the request log.

curl https://ai.eaon.dev/v1/health