Model relay and API keys
Call models with restricted API keys, manage deployments, and inspect settled spending.
A Federation with model relay enabled exposes GET /v1/models and POST /v1/chat/completions. Set your OpenAI client's Base URL to your Federation URL plus /v1. Streaming, non-streaming, tools, and usage share the existing AIService execution and settlement pipeline.
Manage your keys
Website users can manage their own keys in Account → API Keys; the full secret appears only in the successful creation dialog. SDK integrations use the account's login user_token to manage keys. A calling key cannot access account, payment, key management, or request history APIs.
import { Federation } from "@downcity/federation";
const federation = new Federation({
url: "https://your-federation.example",
user_token,
});
const issued = await federation.user.relay.create_key({
name: "Editor",
allowed_models: ["deepseek-v4-flash"],
spend_limit: 10000,
expires_at: null,
});
// Store issued.api_key securely in your calling client; it cannot be retrieved again.
const keys = await federation.user.relay.list_keys();
await federation.user.relay.update_key({ key_id: issued.key.key_id, status: "disabled" });
await federation.user.relay.update_key({ key_id: issued.key.key_id, status: "active" });
await federation.user.relay.revoke_key(issued.key.key_id);allowed_models contains public model or route IDs. [] permits no inference; ["*"] permits all published entries. Access to a route does not grant direct access to its model. Names, permissions, limits, and expiration can be updated. Disabled keys can be reactivated; revoked keys cannot. Disabling or revoking a key blocks new requests, while in-flight requests still settle.
spend_limit is measured in Credits; null means no key spending limit. Before inference, the service checks account balance and the key's successfully settled spending. It does not reserve funds. Concurrent in-flight requests can exceed the configured amount, so this is a soft limit. A key has no separate wallet: charges use the account's existing Credits ledger. Changing the limit does not reset settled lifetime spending; zero blocks new calls. The website shows the actual limit and does not infer used spending when the backend does not provide it.
The key list shows name, status and spending limit. Open a key's name for its permissions, expiration and creation time; use the right-hand actions to edit, disable, reactivate or revoke it. Copy and store a newly issued key before closing its one-time dialog. Never share it or include it in public code.
Use an OpenAI client
Website Models & setup provides the live catalog and backend-declared pricing. Open Set up for the selected model's capabilities, full pricing conditions, public model ID and configuration-derived Base URL. Copy those values into your client. The page never reads a real key; catalog visibility does not grant your key access.
Prices preserve the backend currency, quantity, unit, rate components and applicability dimensions. Multi-component or conditional pricing is not a single flat rate, and missing pricing does not mean free. No Credits conversion or discount is inferred. Unknown context or reasoning options remain undeclared; tools and vision support must not be inferred from model names or tags.
Set FEDERATION_URL to your service address and DOWNCITY_API_KEY to your securely stored calling key. Replace the example model ID below with the model or route ID copied from the catalog.
curl "$FEDERATION_URL/v1/models" \
-H "Authorization: Bearer $DOWNCITY_API_KEY"
curl "$FEDERATION_URL/v1/chat/completions" \
-H "Authorization: Bearer $DOWNCITY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"Hello"}],"stream":true}'Chat Completions supports streaming and non-streaming language calls. Responses and Anthropic Messages are not supported. Native POST /v1/ai/stream also accepts calling keys, using the Downcity Model Protocol's model_id and call:
curl "$FEDERATION_URL/v1/ai/stream" \
-H "Authorization: Bearer $DOWNCITY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"protocol_version":1,"model_id":"deepseek-v4-flash","call":{"messages":[{"role":"user","content":[{"type":"text","text":"Hello"}]}]}}'The native endpoint returns Downcity model-event SSE, not OpenAI SSE; parse it with a client that implements the native protocol. With relay enabled, language endpoints preserve the requested model's capabilities and selling price. They do not automatically switch to another model for new media input. Explicitly select a capable model when needed.
Inspect requests and spending
Website Request history offers your own request pages, key filtering and safe attempt details. The list shows model, execution status, charge and time. Open a model name to inspect the key, request ID, token measurements, duration, settlement and upstream attempts. Filters narrows the list by key; refresh and cursor pagination keep the existing query behavior. Unknown metering and unsettled charges remain unknown rather than zero.
const page = await federation.user.relay.list_requests({ limit: 50 });
const record = page.items[0];
if (record) {
const attempts = await federation.user.relay.list_attempts(record.request_id);
const next_page = await federation.user.relay.list_requests({ before: record.request_id });
}The Federation Router generates a req_<UUID> for each HTTP request and ignores caller-supplied IDs. The relay record's request_id, Action Context.request_id and Context.locals.request_id, and the x-request-id response header all use that same ID; every upstream attempt has its own attempt_id. The Router overwrites the header on success, errors, native Responses, streams, and route 404s without consuming the body or buffering SSE. Framework error bodies and errors after streaming starts follow the HTTP API contract. History includes key ownership, model, channel, tokens, duration, and settlement status. Attempts include time to the first content event. charged_credits is available only after settlement reaches completed. Failed attempts, missing usage, and pending settlement must not be interpreted as zero spending. Logs do not store prompts, responses, calling keys, or provider credentials. Execution, metering and settlement are recorded separately. Requests rejected before upstream execution may have no history record. First-content latency is measured from the logical request start; unknown outcomes do not trigger automatic regeneration.
Enable relay in your Federation
const ai = new AIService({
relay: true,
credits: {
precheck: (user_id, needed_credits) => credits.precheck(user_id, needed_credits),
charge: (input) => credits.charge(input),
},
}).use(models);
federation.use(ai);The first startup imports registered language models into the persistent catalog, retaining their adapters and billing functions. Publish subsequent templates through the management SDK. Public capabilities, reasoning options, and selling prices come from registered templates; operators configure availability, channels, upstream mappings, priorities, weights, and routes. The website provides personal key management. Administrators can use Fedman's Channels & routes page to manage public models, channels, deployments and routes, or use the admin SDK below.
const admin = new Federation({ url: federation_url, admin_token });
const metadata = await admin.admin.relay.metadata(); // Installed templates and adapters, no credentials
const health = await admin.admin.relay.health(); // Shared cooldown snapshot, not an active probe
const snapshot = await admin.admin.relay.catalog();
// Edit snapshot.catalog, then submit the revision that was read.
await admin.admin.relay.configure(snapshot.catalog, snapshot.revision);Fedman derives form choices from the live catalog and metadata(). Create, edit, enable/disable and confirmed deletion use the existing catalog contract. References block deletion; there is no implicit cascade. Saves include the read revision; after a 409 conflict, reload the latest catalog and edit again. Registered channels must be installed and retain fixed runtime mappings. OpenAI channels reference server environment variable names; do not enter secret values. Deployment status shows shared cooldowns only. No cooldown record does not imply healthy service; no paid active probe is provided.
The catalog separates Model, Channel, Deployment, and Route. A Model references a capability and price template. A Channel selects the registered or openai_chat_completions adapter. A Deployment maps a public model to a channel and upstream model. A Route chooses deployments of the same public model. Standard OpenAI channels use a credential-free HTTPS API root as base_url and a Federation environment variable name as credential_env; catalog APIs never return credential values. New channels must support the template's declared capabilities.
The default priority_weighted strategy chooses the highest priority tier, then samples positive integer weight values. Direct model calls permit at most two attempts; a route's max_attempts is 1–3. Explicit 401, 403, and 429 rejections allow failover. Network errors, 5xx responses, timeouts, and errors after receiving an upstream stream do not trigger automatic retries. Shared database cooldowns honor Retry-After for 429 responses, capped at five minutes; other failures use short cooldowns. Expired cooldowns allow normal traffic to probe recovery. Channel timeout_ms defaults to 120000 and accepts 1000–300000. It supplies the channel first-useful-output and idle budgets. Useful progress resets idle; it does not reset the total deadline. Channel model_stream can partially override connect_timeout_ms, first_output_timeout_ms, idle_timeout_ms, and total_timeout_ms; establishment defaults to the first-output budget and total defaults to 900000 milliseconds. Establishment means waiting for a response stream, not TCP connection. Federation and HTTP outer limits still apply, so a channel cannot raise their upper bounds. Adapters must honor cancellation. See Calling models for useful progress events.
Retry-After also propagates to clients as an absolute Unix millisecond retry_at_ms deadline. Agent recovery honors this deadline within its step budget, independently of Relay deployment cooldowns. Relay never transparently regenerates after a network error, timeout, or stream failure.
Catalog snapshots are cached for five seconds per instance. Updates require revision to prevent lost writes; other instances see changes within one cache interval. Routing adds no model invocation. Key state is read on every request, while settled spending and account balance checks run in parallel. Requests and attempts are persisted before upstream execution, and shared health is read from the database. Measure the resulting latency in your deployment; it depends on database placement and upstream behavior.
RPM, TPM, global concurrency leases, Responses, Anthropic Messages, and OAuth account pools are not provided yet.