Chat & inference

The four-field OpenAI-compatible request, simple routing aliases, and the headers that explain each market decision.

Owner

Developer Experience

Version

api-2026.07

Verified

2026-07-13

Omnious exposes OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages over one paid lifecycle. Chat completions remain the smallest general-purpose request: four familiar fields.

The complete core request

{
  "model": "auto",
  "messages": [{ "role": "user", "content": "Hello" }],
  "max_tokens": 256,
  "stream": true
}

The auction arrives before the answer

A streamed response starts with one OpenAI-safe metadata chunk whose choices array is empty and whose omnious.type is auction_cleared. Its ranked auction.bids are the executable standing quotes that competed for this request. The winner is named; losing providers are stable positional labels such as rival-1, with their exact signed input and output tariffs. Normal answer deltas follow immediately and are never held for a replay UI.

const omnious = new OmniousClient({
  routerUrl: "https://api.omnious.xyz",
  creditKey: process.env.OMNIOUS_CREDIT_KEY,
});

await omnious.ask("Explain second-score auctions", {
  model: "auto",
  onAuction: ({ auction }) => {
    for (const bid of auction.bids) {
      console.log(bid.rank, bid.provider, bid.price_out, bid.outcome);
    }
  },
  onDelta: (text) => process.stdout.write(text),
});

Choose a route in one word

Most applications should stop there. Price caps, task hints, latency limits, and model allow-lists live on the focused Routing controls page.

Add capabilities only when needed

Harness-native wire formats

Codex and OpenClaw can use POST /v1/responses. Claude Code can use POST /v1/messages plus the local-only /v1/messages/count_tokens estimate. Both adapters map into the same auction, bounded-key reservation, metering, receipt, and unused-credit release as Chat Completions.

Grounded answers, citations, images, and places

Providers describe grounding in different shapes. Omnious preserves those native fields and also adds one provider-neutral omnious.rich envelope. Text remains the compatibility surface; source records, character-range annotations, sourced images, places, and typed display blocks ride beside it. Clients can therefore render inline citation chips and context-aware media without parsing arbitrary model-generated HTML.

{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "The gallery opens at 10:00."
    }
  }],
  "omnious": {
    "rich": {
      "version": 1,
      "sources": [{
        "id": "src_a1b2c3d4",
        "kind": "web",
        "title": "Visitor information",
        "url": "https://example.org/visit",
        "host": "example.org",
        "snippet": "Opening hours and visitor access."
      }],
      "annotations": [{
        "type": "url_citation",
        "start_index": 4,
        "end_index": 11,
        "source_ids": ["src_a1b2c3d4"]
      }],
      "images": [],
      "places": [],
      "blocks": [{
        "id": "block_7c1e9a20",
        "type": "source_list",
        "source_ids": ["src_a1b2c3d4"]
      }]
    }
  }
}

Every image carries both an image_url and the page it came from. Every place carries coordinates, a map URL, and a source name. Unknown source ids are never upgraded into citations. Omnious-owned image and place search uses fixed allowlisted data backends; external URLs are validated before they reach the renderer.

A model may position a supplied image gallery or place list with a validated [[rich:BLOCK_ID]] marker. Only block ids already present in omnious.rich.blocks are honored; unknown ids stay plain text. Streaming clients should wait for the containing paragraph to finish before inserting the block. If no marker is supplied, place media beside its first relevant citation, then fall back to the first completed paragraph. Keep ordinary links inline and show the source registry after the answer.

POST /v1/responses projects the same citation ranges into standard output_text.annotations. Streams emit response.output_text.annotation.added before the completed content part. Chat Completions clients can read omnious.rich from the non-streaming response or the additive SSE frames. Apps that ignore it continue to receive ordinary OpenAI-compatible text.

The Messages adapter preserves adaptive reasoning, output effort, structured JSON output, and strict function tools. Anthropic-native hosted computer tools still fail closed with a capability error; local CUA Driver tools use the ordinary function-tool path and execute only in the explicitly paired Omnious client.

Auction observability

The isolated Claude Code setup includes a native status line plus display-only prompt and completion hooks, so OMNIOUS, the opening RFQ lifecycle, and the actual clear remain visible inside Claude. The display performs a key-scoped read of GET /v1/auctions/latest, not another model call. It emits user-visible status only: no model context, request mutation, provider decision, or response mutation.

Hermes, OpenClaw, and Codex credential setup still installs no observability hook, skill, or executable plugin. After inference is working, users may separately review and opt into their native auction observer.

Every adapter also exposes four views: tape for the compact line, replay for the mechanism and anonymized ranked bids,tree for session and attributed-call grouping, and jsonfor the versioned record. Optional adapters can expose deterministic commands without changing inference configuration. They are not part of the trust-sensitive wallet and credential flow, and failure never changes the original model response.

Read the result

The body keeps the ordinary OpenAI-compatible completion envelope and adds one namespaced omnious object. Non-streaming calls receive it at the top level. Streaming calls receive it as the first metadata event with an empty choices array, followed by normal completion deltas.

That object contains the request id, selected route, auction version, winner, quote count, clearing tariff, and a five-step process from route through RFQ, award, clear, and serve. Its links point to the eventual signed receipt and full reconstructed auction economics; those records can finalize shortly after the response while asynchronous billing settles. The same core facts remain available as response headers:

{
  "id": "chatcmpl_...",
  "object": "chat.completion",
  "choices": [{ "message": { "role": "assistant", "content": "..." } }],
  "usage": { "prompt_tokens": 42, "completion_tokens": 145, "cost": 0.0001555 },
  "omnious": {
    "request_id": "6bd0...",
    "routing": { "requested_model": "auto", "selected_model": "minimax-m2.7" },
    "auction": {
      "version": "second-score/3",
      "mechanism": "second-score",
      "quotes_competing": 3,
      "winner": { "provider": "minimax-mainnet", "model": "minimax-m2.7" },
      "price_setter": "runner-up",
      "bids": [
        { "rank": 1, "provider": "minimax-mainnet", "model": "minimax-m2.7",
          "price_in": 180000, "price_out": 590000, "outcome": "won" },
        { "rank": 2, "provider": "rival-1", "model": "minimax-m2.7",
          "price_in": 210000, "price_out": 680000, "outcome": "lost" },
        { "rank": 3, "provider": "rival-2", "model": "minimax-m2.7",
          "price_in": 260000, "price_out": 740000, "outcome": "lost" }
      ],
      "clear": { "price_in": 210000, "price_out": 680000,
        "unit": "USDC base units per 1M tokens" }
    },
    "process": [
      { "step": "route", "status": "completed" },
      { "step": "rfq", "status": "completed" },
      { "step": "award", "status": "completed" },
      { "step": "clear", "status": "completed" },
      { "step": "serve", "status": "completed" }
    ],
    "links": {
      "receipt": "/v1/receipts/6bd0...",
      "auction": "/v1/analytics/requests/6bd0..."
    }
  }
}