API reference

Base URL: https://ci-ai.duckdns.org/v1 · auth: Authorization: Bearer <key>. Everything below matches the OpenAI spec; vendor extensions go in extra_body.

Authentication

Keys start with ciai_ and are created in the control panel. Treat a key like a password: send it only over HTTPS, rotate from the panel, and scope each key to the models a workload actually needs.

Chat completions

POST /v1/chat/completions
Content-Type: application/json

{
  "model": "auto",              // or a catalogue id, e.g. "gpt-5"
  "messages": [
    {"role": "system", "content": "You are a terse assistant."},
    {"role": "user", "content": "What is 17 * 23?"}
  ],
  "stream": true,
  "temperature": 0.2,
  "tools": [],
  "extra_body": {
    "gateway": {
      "fallback": ["gpt-5", "claude-sonnet-4.5", "deepseek-r2"],
      "cache": "auto",
      "region": "eu"
    }
  }
}

"model": "auto" lets the router choose by your key's policy (quality / cost / latency). Responses carry x-gateway-model, x-gateway-region and, when relevant, x-gateway-fallback and x-gateway-cache: HIT.

Embeddings

POST /v1/embeddings
{ "model": "gemini-embedding-2", "input": ["release notes text"] }

Model list

GET /v1/models
Authorization: Bearer <key>

Returns id, pricing, context size and the open_weights/runs_locally flags for every model a key can use. Response cached for 5 minutes.

Route modifiers & BYOK

Model id suffixes: :fast — lowest latency, :cheap — lowest price, :eu — EU processing only, :exact — no fallbacks. Example: "model": "deepseek-flash-4.1:fast". An unknown suffix returns a 400 error.

BYOK. On Starter and above you can attach your own vendor key in the panel: calls to that vendor go through directly, the gateway fee is waived, while fallbacks and caching keep working.

Streaming (SSE)

Identical to OpenAI: stream: true emits chat.completion.chunk events and ends with [DONE]. Chunks from fallback upstreams keep the same event shape — clients don't need to handle failover.

Errors

StatusCodeMeaning
401invalid_keyMissing, revoked or malformed key
402budget_exceededKey or account hard limit reached
429rate_limitedrpm limit; retry with Retry-After
502upstream_downAll fallbacks failed; safe to retry

Rate limits & quotas

See Pricing for per-tier rpm. Daily token quotas are set per key in the panel; 80% of a quota triggers an email alert. Limits reset at 00:00 UTC.

SDK snippets

# Python — works with the official openai package unchanged
from openai import OpenAI
client = OpenAI(
    base_url="https://ci-ai.duckdns.org/v1",
    api_key=os.environ["CIAI_KEY"],
)
r = client.chat.completions.create(model="auto",
    messages=[{"role": "user", "content": "ping"}])
// Node — openai npm SDK
import OpenAI from "openai";
const client = new OpenAI({
  baseURL: "https://ci-ai.duckdns.org/v1",
  apiKey: process.env.CIAI_KEY,
});
const r = await client.chat.completions.create({
  model: "deepseek-r2",
  messages: [{ role: "user", content: "ping" }],
});

Webhooks

Optional POST callbacks on budget.warning, budget.exceeded and key.rotated. Payloads are signed with an X-Signature-256 HMAC using the key secret.

Changelog