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
| Status | Code | Meaning |
|---|---|---|
| 401 | invalid_key | Missing, revoked or malformed key |
| 402 | budget_exceeded | Key or account hard limit reached |
| 429 | rate_limited | rpm limit; retry with Retry-After |
| 502 | upstream_down | All 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
- — added open-weight models
qwen-flash-next-3.8,qwen3.8-27banddeepseek-flash-4.1, including self-host (local run) support. - — added
gemini-3-pro1M-context mode. - — cache keys can now be namespaced per tenant.
- —
x-gateway-fallbackresponse header.