Routing and aliases

🧠 Routing strategy

Direct provider models

For a discovered model, MultiVibe:

1. Builds the enabled account/provider candidate pool.
2. Excludes active account/model blocks and unsupported model mappings.
3. Avoids a five-hour window near its configured threshold while another eligible candidate remains.
4. Normally prefers the lowest known weekly usage; equal quota tiers alternate across requests.
5. Only when every effective candidate is near its five-hour limit, prefers the greatest known remaining five-hour headroom.
6. Uses weekly reset timing and configured priority as secondary ordering signals.
7. Rotates on quota-like failures and retries bounded transient upstream errors.

Optional CODEX_SESSION_AFFINITY keeps a session on the same eligible account per application and provider. Affinity never bypasses quota or policy filters.

Smart aliases

Aliases are schema-v2 policies. The first matching rule can inspect:

• application and priority;
• reasoning effort and input size;
• text/image/audio/video modalities;
• tool requirements and execution mode;
• day/time windows.

Constraints filter candidates by local/cloud location, predicted wait, context window, and quality. Remaining candidates are scored for latency, cost, quality, and locality. Capacity comes from configured profiles, requests in flight, quota blocks, health/metrics probes, and learned throughput.

Rules can continue to the next rule, queue work, or reject when no destination has capacity. Optional cloud budgets emit application-scoped warnings.

The dashboard includes guided redirect, ordered fallback, and local-to-cloud presets, plus an advanced editor and a no-inference policy simulator. Legacy targets payloads are migrated to schema v2 when accepted.

Image routing

imageRequestModelOverride can redirect image-bearing requests to a currently exposed model or enabled alias. MultiVibe preserves image parts while bridging Chat Completions image_url and Responses input_image payloads.

Admission and deferred jobs

Inference routes accept these optional headers:

Header	Values / meaning
X-MultiVibe-Priority	critical, interactive, standard, or batch
X-MultiVibe-Execution	sync, auto, or defer
X-MultiVibe-Max-Wait-Ms	Maximum admission wait
X-MultiVibe-Deadline	RFC 3339 completion deadline with timezone, for example 2026-09-01T18:00:00Z
X-MultiVibe-Idempotency-Key	Stable application idempotency key
X-MultiVibe-Webhook	Registered application webhook ID

Without opt-in headers, requests retain synchronous behavior unless the selected alias defines defaults. Streaming, WebSocket, and Realtime requests cannot be deferred. A deferred request returns 202 Accepted and a multivibe.job.

For an authenticated, synchronous JSON inference, the same idempotency header also enables a short in-memory single-flight and replay window. The key is isolated by application and inference route. Reusing it with a different JSON payload returns 409; concurrent duplicates share one execution. Responses include X-MultiVibe-Idempotency-Status with created, coalesced, replayed, or bypass.

Direct inference replay is intentionally limited to text-only, non-streaming, stateless requests without tools. Streaming, tool, multimodal, stored, background, and conversation-linked requests bypass this layer. Errors, partial results, tool-call responses, and responses over the configured byte limit are shared only with already waiting followers and are not retained.

curl -X POST http://localhost:1455/v1/responses \
  -H "Authorization: Bearer $MULTIVIBE_API_KEY" \
  -H "content-type: application/json" \
  -H "X-MultiVibe-Priority: batch" \
  -H "X-MultiVibe-Execution: defer" \
  -H "X-MultiVibe-Idempotency-Key: nightly-translation-42" \
  -d '{"model": "gpt-5.3-codex", "input": "..."}'

Job endpoints are application-isolated:

• GET /v1/jobs and GET /v1/jobs/:id
• GET /v1/jobs/:id/result
• GET /v1/jobs/:id/events with Last-Event-ID replay
• DELETE /v1/jobs/:id

Inference responses may include X-MultiVibe-Decision, X-MultiVibe-Priority, X-MultiVibe-Resolved-Model, and X-MultiVibe-Idempotency-Status. Deferred submissions also return a Location header.

For retention, retries, event types, HMAC signatures, polling, and application-side idempotency, read the deferred batch integration guide. The repository also contains a reusable implementation prompt.