Download OpenAPI specification:
0G Router is an API gateway between users and the decentralized 0G Compute Provider network. It provides unified access, fee collection, and intelligent routing for AI inference services.
User funds live in the shared 0G Payment Layer (PL) vault — a multi-app funding pool that other 0G products also draw from. Router does not drain a user's full vault balance up front; it pulls small amounts on demand into its own ledger as inference is consumed.
As a result, the /v1/account/balance endpoint returns the Router ledger only (deposit_balance + credit_balance). It deliberately excludes the PL vault, because vault balance is shared across consumer apps and is not yet committed to Router.
USD accounts: everything in this section describes accounts settling in 0G. USD settlement does not spend from the Payment Layer vault, so do not add a vault balance to either endpoint's response, and the admission rule below does not apply. A wallet that settled in 0G before switching may still have Router pulling its vault into the now-dormant 0G ledger — money neither endpoint reports while the account is in USD mode. See the two endpoints' own descriptions for what a USD account is served.
/balance vs /fundsIf you just want one display balance that already combines both sides, call /v1/account/funds. Router does the aggregation server-side and returns a net total = (deposit + credit − pending_charge) + vault_balance, plus the breakdown. Unlike /balance's total_balance (Router-ledger-only, always ≥ 0), /funds.total includes the full vault and may be negative when the user owes Router (pending_charge exceeds available funds) — render that as "owed to Router".
Use /v1/account/balance (not /funds) for settlement / SDK / mgmt-key integrations that depend on the Router-ledger-only, ≥ 0 figure. And note /funds.total is a wallet-display number: it is not the admission figure — the "can I submit a request" calculation below applies vault_ratio and is computed separately.
An inference request is admitted when the Router ledger, net of what is owed, plus the counted part of the vault covers it:
deposit + credit − pending_charge >= min_cost, ordeposit + credit − pending_charge + vault_balance × vault_ratio >= min_cost (deferred path; the shortfall is recorded as pending_charge and cleared from the next PL pull).Otherwise the request returns 402 insufficient_balance.
After a user's first successful inference charge, the account becomes pull-eligible. A background worker then keeps the Router ledger topped up from the PL vault:
| Parameter | Mainnet value | Meaning |
|---|---|---|
| Scan interval | 3 s | How often Router checks each pull-eligible account |
| Low watermark | 0.1 0G | Pull triggers when effective Router balance drops below this |
| High watermark | 0.5 0G | Target balance after a pull (≈ amount pulled per cycle) |
| Vault ratio | 0.8 | Only 80% of the PL vault counts toward admission (safety margin for the shared pool) |
| min_cost | 0.01 0G | Minimum cost a single request must be able to cover |
Accounts that have only deposited to the vault but never sent an inference request will not trigger a pull.
To gate a submit button before the first request, combine both sides:
available = router.total_balance − pending_charge + vault_balance × vault_ratio
Use vault_ratio from the table above (0.8 on mainnet). Allow submission when available > 0. There is no need to mirror the min_cost floor on the client — Router enforces it at admission time and returns 402 if the request cannot be covered.
Every response carries X-Request-ID, the router's id for the request. It is the request_id in x_0g_trace and in GET /v1/account/usage/history, so record it to match a request to its charge. An async job (video, async image) is the exception: it is charged when it finishes, under its own id, not the submit's.
A request you abandon is still billed. If your client times out or cancels before the response headers arrive, the request keeps running to completion and is charged, but you never receive its X-Request-ID.
Each release is a dated ### vX.Y — YYYY-MM section, newest first, listing the API changes that went live on mainnet in it. Endpoint and field stability is marked inline with [beta].
First tagged release. It covers everything that reached mainnet since the API was first published, grouped by topic. Read Breaking changes before upgrading a client.
Breaking changes
X-Request-ID is minted by the router. A value you send is no longer adopted, and a provider's own x-request-id no longer overwrites it. Read the response header: it is the value in x_0g_trace.request_id and in GET /v1/account/usage/history. To correlate requests across your own systems, send W3C traceparent.POST endpoints). A top-level field with an upper-case letter ("Stream", "reasoningEffort") is ignored. On an end-to-end-encrypted request it is refused with 400 invalid_request_key, as is any body that gives the same field twice. Nested objects and multipart uploads are unaffected.POST /v1/messages streaming: x_0g_trace and web-search annotations are fields on the last message_delta. The separate event: x_0g_trace and event: annotations frames are gone; strict clients (Kilo Code, OpenCode, @ai-sdk/anthropic) aborted on them with invalid_union. message_delta and message_stop now arrive together at the end; with verify_tee: true that can take up to 30 s with no traffic, so set read timeouts above 30 s. Some clients drop unknown fields (@ai-sdk/anthropic, MessageStream.finalMessage()), so read raw stream events.POST /v1/messages refuses Chat Completions fields — reasoning_effort, reasoning, max_completion_tokens, response_format, frequency_penalty, presence_penalty, seed, n, logprobs, top_logprobs, logit_bias, stream_options, parallel_tool_calls, stop — with 400 unsupported_parameter (an explicit null is accepted). Use thinking, output_config.effort and stop_sequences. A model that does not serve the Anthropic format now returns 400 invalid_request_error instead of 503.400 instead of being silently adjusted: image n (image_capabilities.max_n) and size (image_capabilities.size, including the exact size.sizes list where a model has one) on the sync and async image endpoints; video seconds outside the model's range; a video size that is neither pixel dimensions nor one of the model's resolution tiers; and Seedance draft_task content items.POST /v1/audio/transcriptions refuses stream: true (400 unsupported_stream) and response_format text / srt / vtt (400 unsupported_response_format). Use json or verbose_json.{"error": {"message", "type", "code"}} on OpenAI-style endpoints, {"type": "error", "error": {...}} on /v1/messages. Read error.message. The status code is kept, a provider error already in the right envelope passes through unchanged, and the original body is at error.metadata.raw. A streaming request the provider rejects (any status other than 200) is labelled application/json, not text/event-stream. A refusal a provider sends as 200 with only an error body now returns 400.ZG-Res-Key carries the provider's response id, verbatim, and is present only when the provider returns one.min_cost admission floor rose from 0.00001 0G to 0.01 0G. A 0G account below it gets 402; the remaining balance stays on the account and is spendable after a top-up.404 model_not_found for every account. USD accounts used to get 501 usd_not_supported, which now means only that the model exists but cannot be billed in USD.GET /v1/providers: serving_domain is no longer returned for standard endpoints. An endpoint whose trust tier the router cannot classify has no trust_mode (it used to read private) and is not selected by any trust-mode request: a tier-pinned request with nothing else to route to gets 503 no_provider_for_trust_mode, and pinning it by address alongside a trust mode gets 403 trust_mode_mismatch.New endpoints
POST /v1/videos, GET /v1/videos/{id}, GET /v1/videos/{id}/content and GET /v1/videos, in the OpenAI Video API shape. See Video below.POST /v1/responses [beta] — the OpenAI Responses API, for Codex and other Responses clients, on models whose supported_formats include responses (others: 400 model_format_mismatch). Streaming and non-streaming, function and custom tools, and the hosted web_search tool (billed per search). Stateless: previous_response_id, conversation, background and store: true are refused; plugins, attachments, file_search, code_interpreter, image_generation and mcp are not supported. gpt-6-astra is served here and takes reasoning.effort: "max" on this endpoint only.POST /v1/audio/speech [beta] — text-to-speech in the OpenAI speech shape (model, input, voice, response_format default mp3, speed; not streamed), billed per input character. Models have type: "text-to-speech" and publish speech_capabilities: max_input_bytes, response_formats, the speed range, verified voices, and controls (emotion, pitch, volume, language_boost). A request outside them is 400 invalid_request. USD accounts only; a 0G account gets 501 og_not_supported.POST /v1/embeddings [beta] — the OpenAI Embeddings shape (model, input as a string or an array of strings, dimensions, encoding_format), billed on input tokens only.POST /v1/web/search [beta] — {"query": "…"} returns results (title, url, excerpt, publication date when known). For clients that run a web_search function tool themselves, which also works with end-to-end-encrypted models. Billed the per-search fee when results are returned; counts toward the inference rate limit.GET /v1/account, POST /v1/account/onboarded [beta] — {address, created_at, onboarded_at, og_mode_available}. POST stamps onboarded_at once and is idempotent. og_mode_available: false means the client should not offer the 0G↔USD switch.POST /v1/routing/preview [beta] — the providers a request would go to, in fallback order (up to 4), each with the address and provider_identity to pin and the broker endpoint for its enclave key. Nothing is executed or billed. Takes service_type (including embedding, decisions, text-to-image, speech-to-text) and, for chat, api_format (openai or anthropic). Built for end-to-end encryption, below.New error codes
402 insufficient_balance_inflight (/v1/chat/completions, /v1/messages, /v1/responses) — the estimated cost does not fit in the balance not already set aside for your other requests in flight. The estimate is an upper bound using max_tokens, so a max_tokens close to what you need lets more requests run at once. A request with nothing else of yours in flight is never refused this way.429 fair_share_exceeded — the provider is at capacity and you already have more than your share of its concurrent requests. Nothing was sent or charged; honour Retry-After.400 provider_model_mismatch — a pinned provider does not serve the model, service type or API format (was 500). 400 pinned_provider_not_usd_billable — a USD account pinned a provider with no USD price.400 model_format_mismatch — the model is not served on this API format (/v1/chat/completions for an Anthropic-only model, /v1/responses, or a preview with api_format). Check supported_formats on GET /v1/models.400 unsupported_reasoning_effort — a reasoning_effort the model does not accept, refused before sending (today only gpt-6-astra); it used to retry and fail with 500.503 vault_unavailable (0G accounts) — the Payment Layer balance could not be read; safe to retry. It used to be a 402, and a single dropped connection is now retried before you see it.stream_duration_exceeded and upstream_stream_error under Streaming and limits.Video [beta]
POST /v1/videos takes {model, prompt, seconds, size} as JSON, or multipart with a first-frame image for image-to-video, and returns {id, status, provider_address}. seconds is required, except on a Seedance 2.5 edit (below). GET /v1/videos/{id} reports status, and the poll that sees completion settles the charge. GET /v1/videos/{id}/content returns the file and charges first if you never polled. GET /v1/videos lists your jobs, newest first (limit up to 100). Other states: 404 async_job_not_found, 409 video_not_ready, 424 video_job_failed.zg_<provider>_<provider's id>, up to 80 characters: store them as text and send them back verbatim; no provider_address is needed. Older ids keep working, GET /v1/async/jobs/{id} is unchanged, and a damaged id is 400 malformed_job_id. On usage-history rows a video job's request_id is async-<16 hex>-<job id>; read provider_address from the row.seconds is used only when the provider reports none). Prices are in pricing.video (per second) and pricing.variants: each row has dimensions, a unit (video_second, video_clip or video_token) and a final unit_price. In a resolution-only table, a resolution it does not list is billed at video. In a table keyed on resolution and duration_seconds, a request is billed on the shortest row at its resolution that covers the clip, else the table's dearest row. GET /v1/models shows one endpoint's table; read GET /v1/providers, or pin, when the exact table matters. GET /v1/service-types lists video-generation.size: pixel dimensions choose the aspect ratio for text-to-video and have no effect on image-to-video; a tier name from pricing.variants[].dimensions.resolution chooses the tier. The poll reports what was rendered and fills seconds and size when the provider omits them.402 insufficient_balance otherwise). A separate job-count cap scales with your balance and answers 429 video_jobs_in_flight_limit; it counts from submit, so a parallel batch stops at the cap.x_0g_trace, with billing as booked. verify_tee=true answers on a re-poll while the provider keeps the signature (about 20 minutes). tee_verified: false means the attestation is bad; absent means no verdict, never a failure.video_capabilities: input slots list accepts (url, data_uri). Seedance ratio: "adaptive" also works for text-to-video. A Seedance 2.5 edit with a reference_video in metadata.content takes seconds: -1 or no seconds (advertised as auto: -1, auto_with: ["reference_video"]). input_reference.file_id is 400 on Seedance. expires_at on a poll is optional.501 usd_not_supported). A 0G account can use supply-line video models, billed at the clip's settled price converted at the 0G rate in force at submit.Models
-mature versions of Seedream 4.5 / 5.0 Lite / 5.0 Flash and Seedance 2.5 / 2.0 / 2.0 Fast / 2.0 Mini (the same model and price with the vendor's moderation relaxed for adult content, subject to the 0G Terms of Service); gpt-6-astra on /v1/responses. tencent/hy-image-3.5-preview renders up to 4096x4096 (4K tier). Embedding and transcription models priced on input only now appear in the catalog. GET /v1/models is the full list.. or - between digits (claude-opus-4.8 serves claude-opus-4-8); responses carry the listed id.image_capabilities [beta] on image models: max_n, size (min_side, max_side, min_pixels, max_pixels, default, and sizes where only exact sizes are rendered), references, controls and multi_turn. An absent field means no stated limit. async_supported says whether the async image endpoints serve the model; treat 400 model_not_capable on an async submit as "use the synchronous endpoint".pricing.variants / pricing_usd.variants (unit: "image", dimensions.tier, max_pixels); pricing.image is the cheapest tier, and X-0G-Provider-Max-Price-Usd-Image is compared with the dearest. A model billed per token uses pricing.prompt / pricing.completion and lists no pricing.image.400 model_not_capable when none do); architecture.input_modalities lists image exactly then.supported_parameters lists stream on every chat model. created on a model served by several providers is the earliest of them: when the router first saw the model, not its release date.Billing and balances
x_0g_trace.billing always carries currency ("0g" = wei, "usd" = micro-USD), and on the synchronous endpoints total_cost_usd_micro [beta], the cost in micro-USD whatever the account settles in./v1/chat/completions and /v1/messages answers are billed from the body actually returned, and output without a usage report is billed on an estimate (prompt plus text, reasoning and tool-call arguments). A non-streaming request is completed and billed even if you disconnect after it was sent. A stream whose first event is an error is not charged./v1/account/balance and /v1/account/funds report the 0G Pay balance spendable on this service, plus unsettled_charge [beta] for charges not yet sent; credit_used / deposit_used in usage history say what paid; x_0g_trace.billing is the charge itself (rounded up once, minimum one micro-USD for a priced request). Refusals name the cause: 402 pay_no_balance, pay_insufficient_spendable, pay_debt_threshold (top up); 403 pay_account_cap, pay_service_cap (contact support); 503 pay_gate_unavailable (retry). Credit now covers an amount owed. Do not add a Payment Layer vault balance to a USD account's figures.501 usd_not_supported is returned only when none is left.Web search
0g:web_search tool [beta]: add {"type": "0g:web_search"} to tools (max_uses default 1, at most 5) and the model decides when to search. A searching request runs two model turns, both billed (the deciding turn has its own usage row, id suffixed -ws), plus the per-search fee.0g:web_search / 0g:web_fetch: headers are sent as soon as a provider is chosen; while the router searches or reads, the stream carries SSE comments (: 0g web_search query="…", : 0g web_fetch url="…", : ping every 15 s). On /v1/chat/completions the model's reasoning streams while it decides. An error after that point arrives as an in-stream error event, and X-Provider, ZG-Res-Key and Retry-After are not sent.x_0g_trace.billing.web_search_cost; no results means no fee. Searches a provider runs for Anthropic's web_search server tool are billed the same fee.content given as an array, and results state the retrieval date and each source's publication date.Streaming and limits
stream_duration_exceeded; a provider read failure mid-stream ends it with upstream_stream_error; a provider silent for 9 minutes ends it the same way (on /v1/responses, without response.completed). Output streamed before is billed.429 from a provider carries Retry-After (the provider's own, else 5 s).Routing
allow_fallbacks: true with a pinned provider.address now falls back to other providers. A pin with no identity prefers a sibling upstream under the same address while the cheapest one is answering 429; send X-0G-Provider-Identity to pin exactly. x_0g_trace carries provider_identity on successes and on provider errors (which now include x_0g_trace)./v1/chat/completions routes only to providers serving the OpenAI format. On /v1/messages, thinking: {"type": "enabled"} prefers providers that list it, and tool_addition content blocks are turned into tools entries. Conversation affinity also keys on metadata.user_id, which keeps Claude Code sessions on one provider through compaction.User-Agent (0g-router)./v1/messages errors
error.code with the same value as the OpenAI-style endpoints (for example model_not_found, insufficient_balance, pay_debt_threshold), plus the top-level request_id.End-to-end encryption [beta]
_e2ee object and leave them out of the cleartext body: POST /v1/chat/completions (messages, tools), POST /v1/messages (messages, system, tools), POST /v1/images/generations and POST /v1/async/images/generations (prompt), POST /v1/embeddings (input), POST /v1/decisions (state, questions), and POST /v1/audio/transcriptions (a JSON body with file_base64, and filename / language / prompt when sent). Without _e2ee nothing changes.POST /v1/routing/preview and pin both X-0G-Provider-Address and X-0G-Provider-Identity; when falling back, re-seal for each candidate.usage tokens, usage.output_images for images (what you pay for, not n), and usage.seconds or duration for transcriptions. A sealed response without one is 502 invalid_sealed_response and is not billed.400 unsupported_with_e2ee: sealing stream, stream_options or n; plugins (web search) or attachments; a streaming transcription. A sealed field also sent in cleartext is 400 invalid_request. Sealed images need response_format: "b64_json", and sealed transcriptions json or verbose_json.x_0g_trace.tee_verified is absent on sealed requests: verify the enclave's signature in your client. On a sealed /v1/messages stream, restore your model alias client-side. verify_tee, provider and empty plugins / attachments no longer break the seal.Other
POST /v1/auth/privy: an account's wallet is the EVM wallet linked to its Privy user longest.GET /v1/account/balance is now listed in this reference, and the size / seconds behaviour of video models is documented.Returns non-financial metadata for the authenticated wallet: created_at, onboarded_at and og_mode_available. og_mode_available is false when the account is not offered the 0G settlement mode; a client should then hide the 0G↔USD switch. It is always true while the account is in 0G mode or holds a 0G balance (deposit or credit), so those funds stay reachable. onboarded_at is an RFC3339 timestamp once the account has completed or dismissed the new-user onboarding flow, and null until then — a client reads it to decide whether to show onboarding. Set it via POST /account/onboarded. The value is stored per wallet on the server, so it persists across a cleared cache, another browser, and another device.
{- "address": "0x15d34AAf54267DB7D7c367839AAf71A00a2C6A65",
- "created_at": "2026-01-15T10:30:00Z",
- "og_mode_available": true,
- "onboarded_at": "2026-01-15T10:35:00Z"
}Returns the caller's Router ledger balance: deposit_balance (funds Router has already pulled from the Payment Layer vault) plus credit_balance (promo / granted credit). total_balance is the sum of the two.
This endpoint deliberately does not include the PL vault balance. The vault is a shared pool across 0G apps; Router pulls from it incrementally on demand. To predict whether an inference request can be submitted, clients should combine this response with the PL vault balance — see the "Balance model" section in the API description for the formula.
pending_charge is any outstanding debt the user owes Router (created by the deferred-charge path when the ledger was short but the vault could cover the request); it is cleared automatically when the next vault pull lands on chain.
Accounts settling in USD (currency: "usd" in the response) are never served from the Payment Layer vault — USD settlement does not spend from it. Everything above this paragraph describes 0G-settling accounts only: for a USD account do not add a vault balance on top of this response, and there is no vault pull behind pending_charge either — an amount owed there is cleared by the account's own funds, not by a chain deposit. One caveat if this wallet settled in 0G before switching: Router may still be pulling its vault balance into the now-dormant 0G ledger, and neither this endpoint nor /funds reports that money while the account is in USD mode. Moving the account back to 0G settlement is what makes that money visible and spendable again — at the cost of moving billing off USD until you switch back, since only one ledger is live at a time (both are preserved, nothing is lost either way). The route that does it is session-authenticated, so it is a console action rather than something an sk- or mk- caller can perform.
A USD account whose billing 0G Pay serves is additionally answered from 0G Pay rather than from a balance Router holds. deposit_balance and credit_balance then carry the funds and promotional credit held there, reported as what this service can spend: promotional credit that has expired, or that was granted for a different 0G service, is excluded, so this can read lower than 0G Pay's own wallet view. It is the same figure an inference request is admitted against, but a positive value is not a promise of admission — an amount owed (pending_charge, which total_balance does not subtract), a minimum-balance floor, or a hold placed on the account each refuse independently of it. When the balance cannot be established — the billing service is unreachable, or answers something this endpoint will not act on — it returns 503 rather than a stale or empty figure.
For such an account unsettled_charge is the total of charges already made that have not been sent to 0G Pay yet: a request's charge is sent a few seconds after the reply finishes. The other amounts here, and 0G Pay's own balance, do not include it yet; subtract it to show the balance after those charges. It never counts a charge 0G Pay may already have applied, so while a send is in flight or 0G Pay is slow to accept it the result can briefly read high, never low. total_balance does not subtract pending_charge, so if those charges exceed what the account holds, floor the result at 0 here; /account/funds gives the exact net as router.subtotal − router.unsettled_charge. The field is absent for every other account, and when it could not be read.
{- "address": "0x15d34AAf54267DB7D7c367839AAf71A00a2C6A65",
- "balance": "1000000000000000000",
- "credit_balance": "100000000000000000",
- "currency": "0g",
- "deposit_balance": "900000000000000000",
- "pending_charge": "0",
- "total_balance": "1000000000000000000",
- "unsettled_charge": "87"
}Returns a single aggregated view of the caller's funds so clients don't have to combine /account/balance (Router ledger) with the on-chain PaymentVault.balanceOf themselves.
total = router.subtotal + payment_layer.balance, where router.subtotal = deposit + credit − pending_charge (the net Router-ledger position). total is the user's net spendable funds and may be negative when outstanding debt exceeds available funds — render the shortfall as "owed to Router". This differs from /account/balance's total_balance, which keeps a ≥0 contract for settlement / SDK callers and does NOT subtract pending_charge.
payment_layer.balance is the shared Payment Layer vault balance (shared_across_products: true — the vault is a pool across 0G apps, not owned exclusively by Router). queried_at is when that balance was actually read from chain; it is cached (~10s), so on a cache hit it can be up to that TTL in the past — treat it as the value's as-of time, not the request time.
For the Router-ledger-only view that settlement / SDK / mgmt-key integrations depend on, use /account/balance instead.
For accounts settling in USD (currency: "usd") the payment_layer block does not apply — the Payment Layer vault plays no part in USD settlement — and is returned inert: balance is always "0", shared_across_products is false, and queried_at is the time this response was produced, not a chain read. total is therefore the Router-side position alone, and is negative when the amount owed exceeds deposit + credit.
When 0G Pay serves that account's billing, the router figures come from there (deposit = funds, credit = promotional credit spendable on this service, pending_charge = amount owed), on the same spendable basis /account/balance documents, and the endpoint returns 503 when that balance cannot be established. router.unsettled_charge carries the charges not yet sent there, as on /account/balance.
{- "address": "0x15d34AAf54267DB7D7c367839AAf71A00a2C6A65",
- "currency": "0g",
- "payment_layer": {
- "balance": "7086440000000000000",
- "queried_at": "2026-05-25T16:21:00Z",
- "shared_across_products": true
}, - "router": {
- "credit": "3560000000000000",
- "deposit": "300000000000000000",
- "pending_charge": "0",
- "subtotal": "303560000000000000",
- "unsettled_charge": "87"
}, - "total": "7390000000000000000"
}Returns the routing rules that apply to every API key of the account: provider sort order, fallback, required parameters, trust-mode floor, encrypted transit, allowed / blocked models and providers, and price caps. Each rule is null until set. updated_at is null if the rules were never saved. JWT, or a management key with routing:read. These rules are defaults: an API key's own value for a rule replaces the account's for requests made with that key, and a request can override the preferences (sort, allow_fallbacks, require_parameters) and only tighten the rest. [beta]
{- "allow_fallbacks": true,
- "allowed_models": [
- "glm-5"
], - "allowed_providers": [
- {
- "address": "0x1234567890abcdef1234567890abcdef12345678",
- "identity": "aliyun"
}
], - "blocked_models": [
- "claude-opus-5"
], - "blocked_providers": [
- {
- "address": "0x1234567890abcdef1234567890abcdef12345678",
- "identity": "aliyun"
}
], - "encrypted_transit": "required",
- "max_price_usd": {
- "completion": 10,
- "image": 0.04,
- "prompt": 2.5
}, - "require_parameters": false,
- "sort": "price",
- "trust_mode": "verified",
- "updated_at": "2026-11-02T08:00:00Z",
- "warnings": [
- {
- "code": "unknown_provider",
- "field": "blocked_providers",
- "message": "no provider currently matches */acme"
}
]
}Replaces the account's routing rules with the body: a field left out or null is cleared. Unknown fields are rejected. sort is price or latency; trust_mode is standard, verified or private; encrypted_transit is required or null: the account can make end-to-end encryption mandatory, not relax it (off / preferred → 400); a request that allows plaintext says so itself, in the X-0G-Encrypted-Transit header. Models are canonical model ids. A provider is {"address": "0x…"} (every upstream behind that address), {"address": "0x…", "identity": "aliyun"} (one upstream behind it) or {"identity": "aliyun"} (that upstream behind every address). An allowed list must not be empty (use null for no restriction); an empty blocked list is the same as null. max_price_usd takes USD per 1M prompt tokens, USD per 1M completion tokens and USD per image; 0 admits only providers priced at $0. A provider no listing currently matches is saved, with a warnings entry (unknown_provider); a rule some of the account's active API keys replace with their own value is saved with an overridden_by_keys warning naming how many. Saved rules apply to new requests within about 30 seconds. Invalid input → 400 invalid_routing_policy. JWT, or a management key with routing:write. [beta]
Routing rules
| allow_fallbacks | boolean AllowFallbacks: whether a failed request may move to another provider. |
| allowed_models | Array of strings AllowedModels / BlockedModels: canonical model ids. |
Array of objects (github_com_0glabs_0g-router_pkg_routingpolicy.ProviderRef) AllowedProviders / BlockedProviders: see ProviderRef. | |
| blocked_models | Array of strings |
Array of objects (github_com_0glabs_0g-router_pkg_routingpolicy.ProviderRef) | |
| encrypted_transit | string EncryptedTransit: "required", or null. An account or a key can only make encryption mandatory: the E2EE gateway does not trust the router, so a laxer value stored here could never permit plaintext there — only the caller's own X-0G-Encrypted-Transit header can (see SettableTransit). |
object (github_com_0glabs_0g-router_pkg_routingpolicy.MaxPriceUSD) | |
| require_parameters | boolean RequireParameters: route only to providers that advertise every sampling / reasoning parameter the request uses. |
| sort | string Sort: "price" | "latency". |
| trust_mode | string TrustMode: "standard" | "verified" | "private" (a floor). |
{- "allow_fallbacks": true,
- "allowed_models": [
- "glm-5"
], - "allowed_providers": [
- {
- "address": "0x1234567890abcdef1234567890abcdef12345678",
- "identity": "aliyun"
}
], - "blocked_models": [
- "claude-opus-5"
], - "blocked_providers": [
- {
- "address": "0x1234567890abcdef1234567890abcdef12345678",
- "identity": "aliyun"
}
], - "encrypted_transit": "required",
- "max_price_usd": {
- "completion": 10,
- "image": 0.04,
- "prompt": 2.5
}, - "require_parameters": false,
- "sort": "price",
- "trust_mode": "verified"
}{- "allow_fallbacks": true,
- "allowed_models": [
- "glm-5"
], - "allowed_providers": [
- {
- "address": "0x1234567890abcdef1234567890abcdef12345678",
- "identity": "aliyun"
}
], - "blocked_models": [
- "claude-opus-5"
], - "blocked_providers": [
- {
- "address": "0x1234567890abcdef1234567890abcdef12345678",
- "identity": "aliyun"
}
], - "encrypted_transit": "required",
- "max_price_usd": {
- "completion": 10,
- "image": 0.04,
- "prompt": 2.5
}, - "require_parameters": false,
- "sort": "price",
- "trust_mode": "verified",
- "updated_at": "2026-11-02T08:00:00Z",
- "warnings": [
- {
- "code": "unknown_provider",
- "field": "blocked_providers",
- "message": "no provider currently matches */acme"
}
]
}Shows how a request for model would be routed: every provider of the model, the routable ones first in the order a request tries them, then the excluded ones (this array order is guaranteed). Each routable one has a route (primary, then fallback; not_used when fallbacks are off; skipped when a retry passes over it because the same upstream — its provider_identity, else its address — already failed; not_tried past the retry budget) — providers equal on the sort key share a tie_group, across which routing spreads traffic, so their order within it is not a ranking and can change between calls — and for each excluded one every reason (unhealthy, expired, not_capable, not_allowed, blocked, below_trust_mode, not_encryptable, over_price_cap, settlement_currency, not_billable, not_ranked) with the rule layer that excluded it when a rule did. outcome says whether the request would be routed, and if not, the status and error code it would get. The account's routing rules apply, as GET /v1/account/routing returns them, or account_routing in their place (unsaved edits, validated as PUT /v1/account/routing validates them). With api_key_id, the rules of that key (one of the caller's inference keys) apply on top, a key's own value for a rule replacing the account's (a revoked or expired key's outcome is 401 invalid_api_key, as a request with it gets); with api_key_routing, those rules apply instead of the saved ones (unsaved edits, or a key not created yet), validated as PUT /v1/api-keys/{keyId}/routing validates them. rule_sources names, for each rule set, whether the account's or the key's value applies; an exclusion's layer is account, api_key or request. encrypted_transit is the effective end-to-end encryption requirement (preferred — the default — or required); under required only providers a request can be sealed to are routable (not_encryptable excludes the rest). A preview model the caller is not listed for answers exactly like a model that does not exist (404 model_not_found, no canonical_id, no providers). api_format picks the chat surface explained: openai (/v1/chat/completions, the default) or anthropic (/v1/messages); each routes only to providers of its own format. A failure to compute the explanation (a database error) is a 500, not an outcome. Nothing is executed or billed, and no routing metrics are recorded. JWT, or a management key with routing:read (and keys:read to name an api_key_id). [beta]
Explain request
object AccountRouting previews these account rules instead of the saved ones (unsaved edits on the Routing page). Same shape and validation as PUT /v1/account/routing. | |
| api_format | string APIFormat is the chatbot surface explained: openai (/v1/chat/completions, the default) | anthropic (/v1/messages). Each endpoint routes only to providers of its own format, so there is no "either": a preview mixing both would rank providers no request uses. |
| api_key_id | string APIKeyID previews the routing of requests made with this key (one of the caller's own inference keys), under its saved rules. |
object APIKeyRouting previews these key rules instead of the saved ones — unsaved edits in the key dialog, or a key not created yet (without api_key_id). Same shape and validation as PUT /v1/api-keys/{keyId}/routing. | |
| model | string Model is required: any name the router accepts (canonical id or alias). |
| service_type | string ServiceType defaults to chatbot. Same vocabulary as /v1/routing/preview. |
{- "account_routing": {
- "allow_fallbacks": true,
- "allowed_models": [
- "glm-5"
], - "allowed_providers": [
- {
- "address": "0x1234567890abcdef1234567890abcdef12345678",
- "identity": "aliyun"
}
], - "blocked_models": [
- "claude-opus-5"
], - "blocked_providers": [
- {
- "address": "0x1234567890abcdef1234567890abcdef12345678",
- "identity": "aliyun"
}
], - "encrypted_transit": "required",
- "max_price_usd": {
- "completion": 10,
- "image": 0.04,
- "prompt": 2.5
}, - "require_parameters": false,
- "sort": "price",
- "trust_mode": "verified"
}, - "api_format": "openai",
- "api_key_id": "3f2a6c1e-8d4b-4f0a-9c7e-1b2d3e4f5a6b",
- "api_key_routing": {
- "allow_fallbacks": true,
- "allowed_models": [
- "glm-5"
], - "allowed_providers": [
- {
- "address": "0x1234567890abcdef1234567890abcdef12345678",
- "identity": "aliyun"
}
], - "blocked_models": [
- "claude-opus-5"
], - "blocked_providers": [
- {
- "address": "0x1234567890abcdef1234567890abcdef12345678",
- "identity": "aliyun"
}
], - "encrypted_transit": "required",
- "max_price_usd": {
- "completion": 10,
- "image": 0.04,
- "prompt": 2.5
}, - "require_parameters": false,
- "sort": "price",
- "trust_mode": "verified"
}, - "model": "glm-5.3",
- "service_type": "chatbot"
}{- "allow_fallbacks": true,
- "canonical_id": "glm-5.3",
- "encrypted_transit": "preferred",
- "max_attempts": 4,
- "model": "glm-5.3",
- "object": "routing.explanation",
- "outcome": {
- "code": "provider_not_allowed",
- "message": "provider not allowed: no provider of glm-5.3 passes the provider rules (allowed by api_key)",
- "ok": false,
- "status": 403
}, - "providers": [
- {
- "address": "0x1234567890abcdef",
- "architecture": {
- "input_modalities": [
- "string"
], - "instruct_type": "string",
- "max_input_bytes": {
- "property1": 0,
- "property2": 0
}, - "modality": "string",
- "output_modalities": [
- "string"
], - "tokenizer": "string",
- "url_input_modalities": [
- "string"
]
}, - "canonical_id": "glm-5.1",
- "context_length": 0,
- "default_parameters": {
- "property1": null,
- "property2": null
}, - "exclusions": [
- {
- "layer": "api_key",
- "reason": "over_price_cap"
}
], - "expiration_date": "string",
- "is_healthy": true,
- "latency": 150,
- "max_completion_tokens": 0,
- "model_id": "qwen-2.5-7b-instruct",
- "name": "string",
- "pricing": {
- "cache_write": "string",
- "cache_write_1h": "string",
- "cached_prompt": "string",
- "completion": "string",
- "image": "string",
- "modality_pricing": {
- "input": {
- "property1": "string",
- "property2": "string"
}, - "output": {
- "property1": "string",
- "property2": "string"
}
}, - "prompt": "string",
- "tiered_pricing": [
- {
- "cached_prompt": "string",
- "completion": "string",
- "max_input_tokens": 0,
- "prompt": "string"
}
], - "variants": [
- {
- "dimensions": {
- "property1": "string",
- "property2": "string"
}, - "unit": "string",
- "unit_price": "string"
}
], - "video": "string",
- "video_unit": "string"
}, - "pricing_usd": {
- "cache_write": "string",
- "cache_write_1h": "string",
- "cached_prompt": "string",
- "completion": "string",
- "image": "string",
- "modality_pricing": {
- "input": {
- "property1": "string",
- "property2": "string"
}, - "output": {
- "property1": "string",
- "property2": "string"
}
}, - "prompt": "string",
- "tiered_pricing": [
- {
- "cached_prompt": "string",
- "completion": "string",
- "max_input_tokens": 0,
- "prompt": "string"
}
], - "variants": [
- {
- "dimensions": {
- "property1": "string",
- "property2": "string"
}, - "unit": "string",
- "unit_price": "string"
}
], - "video": "string",
- "video_unit": "string"
}, - "provider_country": "string",
- "provider_identity": "aliyun",
- "provider_name": "string",
- "route": "fallback",
- "service_type": "chatbot",
- "serving_domain": "string",
- "supported_formats": [
- "string"
], - "supported_parameters": [
- "string"
], - "tee_acknowledged": true,
- "tee_attested": true,
- "tee_type": "string",
- "tee_verifier": "string",
- "tie_group": 1,
- "trust_mode": "string",
- "type": "string",
- "uptime": 99.5,
- "verifiability": "string"
}
], - "routable": 4,
- "rule_sources": {
- "sort": "api_key",
- "trust_mode": "account"
}, - "service_type": "chatbot",
- "settlement": "0g",
- "sort": "price",
- "total": 6
}Get usage statistics broken down by day for current user, with optional filters
| api_key_id | string Filter by API key ID |
| source | string Filter by source: 'wallet' (JWT/browser), 'api_key' (any API key), or omit for all |
| start_date | string Start date (YYYY-MM-DD, inclusive) |
| end_date | string End date (YYYY-MM-DD, inclusive) |
| trust_mode | string Filter by trust tier: 'standard' | 'verified' | 'private'. Omit for all tiers. |
| dimensions | string Extra breakdown dimensions on top of (date, model). Only 'trust_mode' is supported: pass |
{- "currency": "0g",
- "data": [
- {
- "cache_write_1h_tokens": 0,
- "cache_write_tokens": 0,
- "cached_tokens": 3200,
- "canonical_id": "glm-5",
- "cost": "150000000000000",
- "cost_usd_micro": "1234",
- "date": "2024-01-15",
- "input_tokens": 8000,
- "model_id": "glm-5",
- "output_tokens": 4345,
- "request_count": 42,
- "trust_mode": "verified"
}
], - "object": "list"
}Get usage history for current user, with optional filters
| limit | integer Default: 20 Limit number of records |
| offset | integer Default: 0 Offset for pagination (legacy). Ignored when |
| cursor | string [beta] Opaque keyset cursor from a prior page's |
| include_total | boolean Default: true [beta] Include the full-set |
| model_id | string Filter by model ID |
| api_key_id | string Filter by API key ID |
| source | string Filter by source: 'wallet' (JWT/browser), 'api_key' (any API key), or omit for all |
| start_date | string Start date (YYYY-MM-DD, inclusive) |
| end_date | string End date (YYYY-MM-DD, inclusive) |
| trust_mode | string Filter by trust tier: 'standard' | 'verified' | 'private'. Omit for all tiers. |
{- "currency": "0g",
- "data": [
- {
- "api_key_id": "abc12345",
- "cache_write_1h_tokens": 0,
- "cache_write_tokens": 0,
- "cached_tokens": 40,
- "canonical_id": "glm-5",
- "cost": "150000000000000",
- "created_at": "2024-01-15T10:30:00Z",
- "credit_used": "50000000000000",
- "deposit_used": "100000000000000",
- "id": 1,
- "input_tokens": 100,
- "model_id": "qwen-2.5-7b-instruct",
- "output_tokens": 50,
- "provider_address": "0x1234...",
- "provider_identity": "aliyun",
- "request_id": "req_abc123",
- "trust_mode": "verified"
}
], - "limit": 20,
- "next_cursor": "string",
- "object": "list",
- "offset": 0,
- "total": 100
}Get usage statistics for current user, optionally filtered by API key and date range
| api_key_id | string Filter by API key ID |
| source | string Filter by source: 'wallet' (JWT/browser), 'api_key' (any API key), or omit for all |
| start_date | string Start date (YYYY-MM-DD, inclusive) |
| end_date | string End date (YYYY-MM-DD, inclusive) |
| trust_mode | string Filter by trust tier: 'standard' | 'verified' | 'private'. Omit for all tiers. |
{- "completion_tokens": 4345,
- "currency": "0g",
- "prompt_tokens": 8000,
- "total_cost": "1000000000000000",
- "total_requests": 42,
- "total_tokens": 12345
}The account's webhook endpoints (at most 5) with their subscribed events and delivery health. status is healthy (the last delivery succeeded), failing (it did not), no_deliveries (nothing sent yet) or disabled (deliveries failed for 3 days in a row; nothing more is sent — remove the endpoint and add it again). Secrets are never listed. JWT, or a management key with webhooks:read. See the webhooks guide for payloads and signature checks. [beta]
{- "data": [
- {
- "created_at": "string",
- "disabled_at": "string",
- "events": [
- "balance.low",
- "model.down"
], - "id": 12,
- "last_delivery": {
- "at": "string",
- "error": "string",
- "ok": true,
- "status_code": 0
}, - "previous_secret_expires_at": "string",
- "status": "healthy",
}
]
}Registers an https URL on a public host for the given events: balance.low, model.added, model.removed, model.down, model.recovered (at least one). balance.low is available to USD-billed accounts only (otherwise 400 event_not_available). The response carries the signing secret — the only time it is shown; store it. An account can have 5 endpoints (409 webhook_limit_reached). A URL that is not https, has credentials, or points at a private, loopback, link-local, CGNAT or metadata address → 400 invalid_webhook. Deliveries come from no fixed IP address: authenticate them by their signature. JWT, or a management key with webhooks:write. [beta]
Endpoint
| events | Array of strings |
| url | string |
{- "events": [
- "balance.low",
- "model.down"
],
}{- "created_at": "string",
- "disabled_at": "string",
- "events": [
- "balance.low",
- "model.down"
], - "id": 12,
- "last_delivery": {
- "at": "string",
- "error": "string",
- "ok": true,
- "status_code": 0
}, - "previous_secret_expires_at": "string",
- "secret": "whsec_9b1f…",
- "status": "healthy",
}The endpoint's deliveries from the last 30 days, newest first, 50 per page; pass next_before as before for the next page. status is pending (more attempts to come, at next_attempt_at), delivered or abandoned (every attempt failed: retries run 1m, 5m, 30m, 2h, 6h and 12h after the first). JWT, or a management key with webhooks:read. [beta]
| id required | integer Endpoint id |
| before | integer Cursor: deliveries older than this id |
{- "data": [
- {
- "attempts": 0,
- "created_at": "string",
- "error": "string",
- "event_id": "string",
- "event_type": "string",
- "id": 0,
- "last_attempt_at": "string",
- "next_attempt_at": "string",
- "status": "string",
- "status_code": 0,
- "test": true
}
], - "has_more": true,
- "next_before": 0
}Returns a new signing secret — the only time it is shown. For 24 hours deliveries carry two v1= signatures, one per secret, so a receiver can switch over without dropping events; after that only the new secret signs. JWT, or a management key with webhooks:write. [beta]
| id required | integer Endpoint id |
{- "previous_secret_expires_at": "string",
- "secret": "whsec_9b1f…"
}Sends one sample event of the endpoint's first subscribed type, with "test": true, signed like any delivery, and answers with what the receiver did: ok (a 2xx within 10 seconds), its status_code (null if none arrived) and error. Not retried; a failing test does not count towards disabling the endpoint. One test per endpoint every 10 seconds (429 webhook_test_rate_limited, with Retry-After). A failure to connect reads destination not allowed, timed out or could not connect. JWT, or a management key with webhooks:write. [beta]
| id required | integer Endpoint id |
{- "error": "string",
- "event_id": "evt_4f1c2a9b0d3e5f6a7b8c9d0e",
- "ok": true,
- "status_code": 0,
- "type": "balance.low"
}Get all API keys for current user
| status | string Filter: active / revoked / expired / all (default all) |
{- "data": [
- {
- "allowed_models": [
- "[\"glm-5\"]"
], - "allowed_providers": [
- "[\"0xabc...\"]"
], - "created_at": "2024-01-15T10:30:00Z",
- "credit_limit": "1.5",
- "currency": "0g",
- "expires_at": "2025-02-15T10:30:00Z",
- "key_id": "abc12345",
- "key_preview": "sk-abcde…",
- "name": "my-api-key",
- "reset_period": "monthly",
- "revoked": false,
- "routing": {
- "allow_fallbacks": true,
- "allowed_models": [
- "glm-5"
], - "allowed_providers": [
- {
- "address": "0x1234567890abcdef1234567890abcdef12345678",
- "identity": "aliyun"
}
], - "blocked_models": [
- "claude-opus-5"
], - "blocked_providers": [
- {
- "address": "0x1234567890abcdef1234567890abcdef12345678",
- "identity": "aliyun"
}
], - "encrypted_transit": "required",
- "max_price_usd": {
- "completion": 10,
- "image": 0.04,
- "prompt": 2.5
}, - "require_parameters": false,
- "sort": "price",
- "trust_mode": "verified"
}, - "status": "active",
- "trust_mode": "verified",
- "used": "0.42"
}
], - "object": "list"
}Create a new API key for LLM service access
API key configuration
| allowed_models | Array of strings AllowedModels is an optional allowlist of model IDs this key may invoke. Nil = no restriction. Empty slice = explicit empty list, rejected at validation (a key that can call no models is useless). |
| allowed_providers | Array of strings AllowedProviders is an optional allowlist of provider addresses (hex, 0x-prefixed) this key may target. Same nil-vs-empty convention as AllowedModels. |
| credit_limit | string 0G units; nil = unlimited |
| expiration | string RFC3339, "no_expiration", or "" |
| name | string |
| reset_period | string never/daily/weekly/monthly; "" → never |
object Routing optionally sets the key's routing rules at creation, in the shape PUT /v1/api-keys/{keyId}/routing takes. It includes trust_mode, allowed_models and allowed_providers, so set those either here or at the top level, not both (400 invalid_routing_policy). [beta] | |
| trust_mode | string TrustMode optionally pins this key to a single trust tier. Accepted values: "standard" | "verified" | "private" | "" (no pin). The wire shape is a value type rather than a pointer because the create path has no "leave unchanged" semantics — absent / empty / explicit "" all mean "no pin". |
{- "allowed_models": [
- "string"
], - "allowed_providers": [
- "string"
], - "credit_limit": "string",
- "expiration": "string",
- "name": "string",
- "reset_period": "string",
- "routing": {
- "allow_fallbacks": true,
- "allowed_models": [
- "glm-5"
], - "allowed_providers": [
- {
- "address": "0x1234567890abcdef1234567890abcdef12345678",
- "identity": "aliyun"
}
], - "blocked_models": [
- "claude-opus-5"
], - "blocked_providers": [
- {
- "address": "0x1234567890abcdef1234567890abcdef12345678",
- "identity": "aliyun"
}
], - "encrypted_transit": "required",
- "max_price_usd": {
- "completion": 10,
- "image": 0.04,
- "prompt": 2.5
}, - "require_parameters": false,
- "sort": "price",
- "trust_mode": "verified"
}, - "trust_mode": "string"
}{- "allowed_models": [
- "[\"glm-5\"]"
], - "allowed_providers": [
- "[\"0xabc...\"]"
], - "created_at": "2024-01-15T10:30:00Z",
- "credit_limit": "1.5",
- "currency": "0g",
- "expires_at": "2025-02-15T10:30:00Z",
- "key": "string",
- "key_id": "abc12345",
- "key_preview": "sk-abcde…",
- "name": "my-api-key",
- "reset_period": "monthly",
- "revoked": false,
- "routing": {
- "allow_fallbacks": true,
- "allowed_models": [
- "glm-5"
], - "allowed_providers": [
- {
- "address": "0x1234567890abcdef1234567890abcdef12345678",
- "identity": "aliyun"
}
], - "blocked_models": [
- "claude-opus-5"
], - "blocked_providers": [
- {
- "address": "0x1234567890abcdef1234567890abcdef12345678",
- "identity": "aliyun"
}
], - "encrypted_transit": "required",
- "max_price_usd": {
- "completion": 10,
- "image": 0.04,
- "prompt": 2.5
}, - "require_parameters": false,
- "sort": "price",
- "trust_mode": "verified"
}, - "status": "active",
- "trust_mode": "verified",
- "used": "0.42"
}Update name / credit_limit / reset_period / expiration of an API key
| keyId required | string API Key ID |
Patch payload
| allowed_models | Array of strings AllowedModels / AllowedProviders sparse-PATCH sentinels: nil → unchanged non-nil empty [] → clear the allowlist (no restriction) non-nil non-empty → replace the allowlist Pointer to slice (rather than slice) so we can distinguish "leave alone" from "clear", matching how Scopes is handled on mgmt keys. |
| allowed_providers | Array of strings |
| credit_limit | string |
| expiration | string |
| name | string |
| reset_period | string |
| trust_mode | string TrustMode sparse-PATCH sentinels: nil → unchanged; "" → clear the pin (key falls back to no trust-mode restriction); any of standard|verified|private → set the pin. |
{- "allowed_models": [
- "string"
], - "allowed_providers": [
- "string"
], - "credit_limit": "string",
- "expiration": "string",
- "name": "string",
- "reset_period": "string",
- "trust_mode": "string"
}{- "allowed_models": [
- "[\"glm-5\"]"
], - "allowed_providers": [
- "[\"0xabc...\"]"
], - "created_at": "2024-01-15T10:30:00Z",
- "credit_limit": "1.5",
- "currency": "0g",
- "expires_at": "2025-02-15T10:30:00Z",
- "key_id": "abc12345",
- "key_preview": "sk-abcde…",
- "name": "my-api-key",
- "reset_period": "monthly",
- "revoked": false,
- "routing": {
- "allow_fallbacks": true,
- "allowed_models": [
- "glm-5"
], - "allowed_providers": [
- {
- "address": "0x1234567890abcdef1234567890abcdef12345678",
- "identity": "aliyun"
}
], - "blocked_models": [
- "claude-opus-5"
], - "blocked_providers": [
- {
- "address": "0x1234567890abcdef1234567890abcdef12345678",
- "identity": "aliyun"
}
], - "encrypted_transit": "required",
- "max_price_usd": {
- "completion": 10,
- "image": 0.04,
- "prompt": 2.5
}, - "require_parameters": false,
- "sort": "price",
- "trust_mode": "verified"
}, - "status": "active",
- "trust_mode": "verified",
- "used": "0.42"
}Returns one inference API key's routing rules, in the same shape as GET /v1/account/routing. trust_mode, allowed_models and allowed_providers are the same rules the key's own fields of those names carry. JWT, or a management key with keys:read. [beta]
| keyId required | string API Key ID |
{- "allow_fallbacks": true,
- "allowed_models": [
- "glm-5"
], - "allowed_providers": [
- {
- "address": "0x1234567890abcdef1234567890abcdef12345678",
- "identity": "aliyun"
}
], - "blocked_models": [
- "claude-opus-5"
], - "blocked_providers": [
- {
- "address": "0x1234567890abcdef1234567890abcdef12345678",
- "identity": "aliyun"
}
], - "encrypted_transit": "required",
- "key_id": "3f2a6c1e-8d4b-4f0a-9c7e-1b2d3e4f5a6b",
- "max_price_usd": {
- "completion": 10,
- "image": 0.04,
- "prompt": 2.5
}, - "require_parameters": false,
- "sort": "price",
- "trust_mode": "verified",
- "warnings": [
- {
- "code": "unknown_provider",
- "field": "blocked_providers",
- "message": "no provider currently matches */acme"
}
]
}Replaces one inference API key's routing rules with the body, with the same fields and validation as PUT /v1/account/routing: a field left out or null is cleared — including trust_mode, allowed_models and allowed_providers, which are the key's fields of those names. A field the key sets replaces the account's rule of that name for requests made with the key; null inherits the account's. One difference from the account: an empty list ([], allowed or blocked) is accepted and kept — it means "no restriction from this list" and replaces the account's list instead of inheriting it, and reads back as []. A revoked key → 410 key_revoked. JWT, or a management key with keys:manage. [beta]
| keyId required | string API Key ID |
Routing rules
| allow_fallbacks | boolean AllowFallbacks: whether a failed request may move to another provider. |
| allowed_models | Array of strings AllowedModels / BlockedModels: canonical model ids. |
Array of objects (github_com_0glabs_0g-router_pkg_routingpolicy.ProviderRef) AllowedProviders / BlockedProviders: see ProviderRef. | |
| blocked_models | Array of strings |
Array of objects (github_com_0glabs_0g-router_pkg_routingpolicy.ProviderRef) | |
| encrypted_transit | string EncryptedTransit: "required", or null. An account or a key can only make encryption mandatory: the E2EE gateway does not trust the router, so a laxer value stored here could never permit plaintext there — only the caller's own X-0G-Encrypted-Transit header can (see SettableTransit). |
object (github_com_0glabs_0g-router_pkg_routingpolicy.MaxPriceUSD) | |
| require_parameters | boolean RequireParameters: route only to providers that advertise every sampling / reasoning parameter the request uses. |
| sort | string Sort: "price" | "latency". |
| trust_mode | string TrustMode: "standard" | "verified" | "private" (a floor). |
{- "allow_fallbacks": true,
- "allowed_models": [
- "glm-5"
], - "allowed_providers": [
- {
- "address": "0x1234567890abcdef1234567890abcdef12345678",
- "identity": "aliyun"
}
], - "blocked_models": [
- "claude-opus-5"
], - "blocked_providers": [
- {
- "address": "0x1234567890abcdef1234567890abcdef12345678",
- "identity": "aliyun"
}
], - "encrypted_transit": "required",
- "max_price_usd": {
- "completion": 10,
- "image": 0.04,
- "prompt": 2.5
}, - "require_parameters": false,
- "sort": "price",
- "trust_mode": "verified"
}{- "allow_fallbacks": true,
- "allowed_models": [
- "glm-5"
], - "allowed_providers": [
- {
- "address": "0x1234567890abcdef1234567890abcdef12345678",
- "identity": "aliyun"
}
], - "blocked_models": [
- "claude-opus-5"
], - "blocked_providers": [
- {
- "address": "0x1234567890abcdef1234567890abcdef12345678",
- "identity": "aliyun"
}
], - "encrypted_transit": "required",
- "key_id": "3f2a6c1e-8d4b-4f0a-9c7e-1b2d3e4f5a6b",
- "max_price_usd": {
- "completion": 10,
- "image": 0.04,
- "prompt": 2.5
}, - "require_parameters": false,
- "sort": "price",
- "trust_mode": "verified",
- "warnings": [
- {
- "code": "unknown_provider",
- "field": "blocked_providers",
- "message": "no provider currently matches */acme"
}
]
}Submit an image editing job to be processed asynchronously. The response includes jobId and provider_address — clients then poll /v1/async/jobs/{jobId} with ?provider_address=... to retrieve the result.
Supports provider routing preferences via X-0G-Provider-* request headers (Address, Sort, Trust-Mode, Allow-Fallbacks). Multipart endpoints have no body-side routing surface — headers only.
| X-0G-Provider-Address | string Routing: pin to a specific provider by on-chain address (0x-prefixed). |
| X-0G-Provider-Sort | string Routing: provider sort strategy. |
| X-0G-Provider-Trust-Mode | string Routing: trust tier filter ( |
| X-0G-Provider-Allow-Fallbacks | string Routing: whether to retry on other providers after a failure. |
| X-0G-Provider-Allow | string Routing: only these providers, comma-separated: |
| X-0G-Provider-Block | string Routing: never these providers, same forms as X-0G-Provider-Allow. Adds to the API key's own blocked providers. [beta] |
{ }Submit an image generation job to be processed asynchronously. The response includes jobId and provider_address — clients then poll /v1/async/jobs/{jobId} with ?provider_address=... to retrieve the result.
Provider Routing: Use "provider": {...} body field OR X-0G-Provider-* request headers. Header > body precedence resolves same-field conflicts.
End-to-end encryption [beta]: a 0G Private Computer client may seal prompt into a top-level _e2ee object and omit the cleartext prompt. The completed poll response is then sealed too: data is encrypted to the client and usage.output_images (cleartext) is the billed count. A sealed body must not also carry a top-level prompt (400 invalid_request) or plugins/attachments (400 unsupported_with_e2ee); a sealed result without a usable usage.output_images is refused with 502 invalid_sealed_response and not charged.
| X-0G-Provider-Address | string Routing: pin to a specific provider by on-chain address (0x-prefixed). |
| X-0G-Provider-Sort | string Routing: provider sort strategy. |
| X-0G-Provider-Trust-Mode | string Routing: trust tier filter ( |
| X-0G-Provider-Allow-Fallbacks | string Routing: whether to retry on other providers after a failure. |
| X-0G-Provider-Allow | string Routing: only these providers, comma-separated: |
| X-0G-Provider-Block | string Routing: never these providers, same forms as X-0G-Provider-Allow. Adds to the API key's own blocked providers. [beta] |
Image generation request
| model | string Model ID |
| n | integer Number of images to generate |
| prompt | string Image description |
| response_format | string Response format: url or b64_json |
| size | string Image size |
{- "model": "dall-e-3",
- "n": 1,
- "prompt": "A beautiful sunset",
- "response_format": "url",
- "size": "1024x1024"
}{ }Generate audio from the input text. Request fields: model, input, voice, response_format (mp3 default, opus, aac, flac, wav, pcm — a model may support fewer and answers 400 for the rest), speed (0.25–4.0), the provider routing preferences (see /chat/completions), and the optional fields the model lists in speech_capabilities.controls on GET /v1/models (e.g. emotion, pitch, volume, language_boost). A model's speech_capabilities also bound input (max_input_bytes, UTF-8), response_format and speed; a request outside them is refused with 400 before it is sent. Any other field is refused with 400; stream_format is accepted only as "audio" — the response is the whole audio file. voice takes the model's own voice ids (speech_capabilities.voices lists verified ones). Billed per input character at the model's pricing.prompt (USD per character); available to USD-settled accounts. [beta]
| X-0G-Provider-Address | string Routing: pin to a specific provider by on-chain address (0x-prefixed). |
| X-0G-Provider-Allow-Fallbacks | string Routing: whether to retry on other providers after a failure. |
| X-0G-Provider-Allow | string Routing: only these providers, comma-separated: |
| X-0G-Provider-Block | string Routing: never these providers, same forms as X-0G-Provider-Allow. Adds to the API key's own blocked providers. [beta] |
Speech request
| input | string |
| model | string |
| response_format | string |
| speed | number |
| voice | string |
{- "input": "string",
- "model": "string",
- "response_format": "string",
- "speed": 0,
- "voice": "string"
}Transcribe audio file to text. Accepts either content type:
application/json (default, schema below): AudioTranscriptionRequest body with base64-encoded audio in file_base64.multipart/form-data (OpenAI-style): file part with audio bytes + model form field (plus optional language, response_format). Schema not auto-documented here — matches the OpenAI /v1/audio/transcriptions shape.
response_format accepts json (the default) or verbose_json. text, srt and vtt are refused with 400 unsupported_response_format.
Streaming is not supported: stream: true is refused with 400 unsupported_stream.
Supports provider routing preferences via X-0G-Provider-* request headers (Address, Sort, Trust-Mode, Allow-Fallbacks). Multipart requests have no body-side routing surface — headers only. JSON requests may also use the body provider: {...} field.| X-0G-Provider-Address | string Routing: pin to a specific provider by on-chain address (0x-prefixed). |
| X-0G-Provider-Sort | string Routing: provider sort strategy. |
| X-0G-Provider-Trust-Mode | string Routing: trust tier filter ( |
| X-0G-Provider-Allow-Fallbacks | string Routing: whether to retry on other providers after a failure. |
| X-0G-Provider-Allow | string Routing: only these providers, comma-separated: |
| X-0G-Provider-Block | string Routing: never these providers, same forms as X-0G-Provider-Allow. Adds to the API key's own blocked providers. [beta] |
JSON-body shape (base64-encoded audio in file_base64). For multipart/form-data requests, send file + model form parts instead — see description.
| file_base64 | string Base64 encoded audio file |
| filename | string Filename |
| language | string Audio language |
| model | string Model ID |
| response_format | string Response format |
{- "file_base64": "SGVsbG8gd29ybGQ=",
- "filename": "audio.mp3",
- "language": "en",
- "model": "whisper-1",
- "response_format": "json"
}{- "duration": 5.5,
- "language": "en",
- "text": "Hello, world!"
}Send chat request to AI provider (OpenAI compatible API).
Web Search: Add "plugins": [{"id": "web"}] to enable real-time web search.
Search results are injected into the prompt context and returned as url_citation annotations
in the response. Works with any model. Multi-turn conversations automatically rewrite
the query for better search relevance. The injected search context tokens are billed
as normal input tokens.
File Attachments: Upload via POST /v1/files, then reference with
"attachments": [{"file_id": "file-..."}]. Extracted text is injected into the system prompt
and billed as normal input tokens.
Provider Routing: Use "provider": {"sort": "latency"|"price", "address": "0x...", "allow_fallbacks": true}
to influence provider selection. address overrides sort. The X-0G-Provider-* request headers (documented below) are the equivalent canonical surface.
Price Ceiling (header-only): set X-0G-Provider-Max-Price-Usd-Prompt / -Completion (USD per 1M tokens)
or -Image (USD per generated image). Providers above the cap are excluded before sort/fallback runs. [beta]
E2EE (sealed requests): a 0G Private Computer sidecar may seal messages/tools into a top-level
_e2ee object and omit them from the cleartext body. The router detects _e2ee, skips the
messages-required check, and carries the _e2ee field through to the provider (which it never
reads or decrypts); model and response usage stay cleartext for routing/billing. Presence of
_e2ee is the only signal (no header). [beta]
| X-0G-Provider-Address | string Routing: pin to a specific provider by on-chain address (0x-prefixed). |
| X-0G-Provider-Sort | string Routing: provider sort strategy. |
| X-0G-Provider-Trust-Mode | string Routing: trust tier filter ( |
| X-0G-Provider-Allow-Fallbacks | string Routing: whether to retry on other providers after a failure. |
| X-0G-Provider-Allow | string Routing: only these providers, comma-separated: |
| X-0G-Provider-Block | string Routing: never these providers, same forms as X-0G-Provider-Allow. Adds to the API key's own blocked providers. [beta] |
Chat request
Array of objects (github_com_0glabs_0g-router_pkg_inference.Attachment) File attachments (uploaded via /v1/files) | |
| max_tokens | integer Maximum output tokens |
Array of objects (github_com_0glabs_0g-router_pkg_inference.RequestMessage) Message list (content may be string or multimodal array) | |
| model | string Model ID |
Array of objects (github_com_0glabs_0g-router_pkg_inference.Plugin) Plugins to enable (e.g. [{"id":"web"}] for web search) | |
object Routing preferences (0G Router extension) | |
object Output format: json_object or json_schema for structured output | |
| stream | boolean Whether to stream output |
| temperature | number Temperature parameter (0-2) |
| tool_choice | any Which tool to use: "none", "auto", "required", or {"type":"function","function":{"name":"..."}} |
Array of objects (github_com_0glabs_0g-router_pkg_inference.Tool) Tools (functions) the model may call | |
| top_p | number Top-p sampling parameter |
{- "attachments": [
- {
- "file_id": "file-abc123"
}
], - "max_tokens": 1024,
- "messages": [
- {
- "content": "Hello!",
- "role": "user"
}
], - "model": "qwen/qwen-2.5-7b-instruct",
- "plugins": [
- {
- "id": "web"
}
], - "provider": {
- "address": "0x1234...",
- "allow_fallbacks": true,
- "sort": "latency",
- "trust_mode": "verified"
}, - "response_format": {
- "json_schema": null,
- "type": "json_schema"
}, - "stream": false,
- "temperature": 0.7,
- "tool_choice": null,
- "tools": [
- {
- "function": {
- "description": "Get weather",
- "name": "get_weather",
- "parameters": null
}, - "type": "function"
}
], - "top_p": 0.9
}{- "choices": [
- {
- "delta": {
- "content": "string",
- "reasoning": "string",
- "reasoning_content": "string",
- "role": "string"
}, - "finish_reason": "stop",
- "index": 0,
- "message": {
- "content": "Hello!",
- "role": "user"
}
}
], - "created": 1677652288,
- "id": "chatcmpl-123",
- "model": "qwen/qwen-2.5-7b-instruct",
- "object": "chat.completion",
- "usage": {
- "completion_tokens": 20,
- "completion_tokens_details": {
- "audio_tokens": 0,
- "text_tokens": 0
}, - "prompt_tokens": 10,
- "prompt_tokens_details": {
- "audio_tokens": 0,
- "cache_write_1h_tokens": 0,
- "cache_write_tokens": 0,
- "cached_tokens": 0,
- "image_tokens": 0,
- "text_tokens": 0,
- "video_tokens": 0
}, - "total_tokens": 30
}, - "x_0g_trace": {
- "billing": {
- "currency": "usd",
- "input_cost": "0.00001",
- "output_cost": "0.00002",
- "total_cost": "0.00003",
- "total_cost_usd_micro": "1500",
- "web_fetch_cost": "3000",
- "web_search_cost": "20000"
}, - "provider": "0x1234...",
- "provider_identity": "anonymous1",
- "request_id": "req_abc123",
- "request_rewritten": [
- "string"
], - "tee_verified": true
}
}Ask a decision model (TypeSafe Jev) one or more typed questions about state. questions is an object of named questions, each {"type":"noul"|"choice"|"score","instructions":...,"criteria":...}; the response carries a typed answer with a probability per question, never generated text. Synchronous: one JSON response, no streaming. Supports provider routing preferences (see /chat/completions).
E2EE (sealed requests): a 0G Private Computer client may seal state and questions into a top-level _e2ee object and omit them from the cleartext body. The router skips the required-field checks for such a body and forwards _e2ee to the provider without reading it; model stays cleartext for routing. The response seals answers and carries the billable usage.input_tokens in cleartext. A sealed request must not also carry a top-level state or questions, and attachments is refused on a sealed request (unsupported_with_e2ee). [beta]
| X-0G-Provider-Address | string Routing: pin to a specific provider by on-chain address (0x-prefixed). |
| X-0G-Provider-Sort | string Routing: provider sort strategy. |
| X-0G-Provider-Trust-Mode | string Routing: trust tier filter ( |
| X-0G-Provider-Allow-Fallbacks | string Routing: whether to retry on other providers after a failure. |
| X-0G-Provider-Allow | string Routing: only these providers, comma-separated: |
| X-0G-Provider-Block | string Routing: never these providers, same forms as X-0G-Provider-Allow. Adds to the API key's own blocked providers. [beta] |
Decisions request
| model | string Model ID |
| questions | Array of integers Named typed questions |
| state | Array of integers App state the questions are asked about |
{- "model": "jev-1.13",
- "questions": [
- 0
], - "state": [
- 0
]
}{ }Create a vector embedding for the given input text. Supports provider routing preferences (see /chat/completions).
E2EE (sealed requests): a 0G Private Computer client may seal input into a top-level _e2ee object and omit it from the cleartext body. The router skips the input-required check for such a body and forwards _e2ee to the provider without reading it; model, dimensions and encoding_format stay cleartext for routing. The response seals data (the vectors) and carries the billable usage.prompt_tokens in cleartext. A sealed request must not also carry a top-level input, and attachments is refused on a sealed request (unsupported_with_e2ee). [beta]
| X-0G-Provider-Address | string Routing: pin to a specific provider by on-chain address (0x-prefixed). |
| X-0G-Provider-Sort | string Routing: provider sort strategy. |
| X-0G-Provider-Trust-Mode | string Routing: trust tier filter ( |
| X-0G-Provider-Allow-Fallbacks | string Routing: whether to retry on other providers after a failure. |
| X-0G-Provider-Allow | string Routing: only these providers, comma-separated: |
| X-0G-Provider-Block | string Routing: never these providers, same forms as X-0G-Provider-Allow. Adds to the API key's own blocked providers. [beta] |
Embedding request
| input | Array of integers Text (or array of texts / token arrays) to embed |
| model | string Model ID |
{- "input": [
- 0
], - "model": "qwen3.7-text-embedding"
}{ }Edit an image using AI (inpainting, variations). The n and size form fields are held to the model's image_capabilities on GET /v1/models, as on /images/generations.
Supports provider routing preferences via X-0G-Provider-* request headers (Address, Sort, Trust-Mode, Allow-Fallbacks). Multipart endpoints have no body-side routing surface — headers only.
| X-0G-Provider-Address | string Routing: pin to a specific provider by on-chain address (0x-prefixed). |
| X-0G-Provider-Sort | string Routing: provider sort strategy. |
| X-0G-Provider-Trust-Mode | string Routing: trust tier filter ( |
| X-0G-Provider-Allow-Fallbacks | string Routing: whether to retry on other providers after a failure. |
| X-0G-Provider-Allow | string Routing: only these providers, comma-separated: |
| X-0G-Provider-Block | string Routing: never these providers, same forms as X-0G-Provider-Allow. Adds to the API key's own blocked providers. [beta] |
| image | string <binary> Source image file |
| prompt required | string Edit instruction |
| model required | string Model ID |
{- "created": 1677652288,
}Generate images using AI. Supports provider routing preferences (see /chat/completions). n and size must lie within the model's image_capabilities on GET /v1/models (max_n; size.min_side/max_side/min_pixels/max_pixels, and size.sizes — the only sizes the model renders — when listed); a request outside them is refused with 400 before it is sent.
| X-0G-Provider-Address | string Routing: pin to a specific provider by on-chain address (0x-prefixed). |
| X-0G-Provider-Sort | string Routing: provider sort strategy. |
| X-0G-Provider-Trust-Mode | string Routing: trust tier filter ( |
| X-0G-Provider-Allow-Fallbacks | string Routing: whether to retry on other providers after a failure. |
| X-0G-Provider-Allow | string Routing: only these providers, comma-separated: |
| X-0G-Provider-Block | string Routing: never these providers, same forms as X-0G-Provider-Allow. Adds to the API key's own blocked providers. [beta] |
Image generation request
| model | string Model ID |
| n | integer Number of images to generate |
| prompt | string Image description |
| response_format | string Response format: url or b64_json |
| size | string Image size |
{- "model": "dall-e-3",
- "n": 1,
- "prompt": "A beautiful sunset",
- "response_format": "url",
- "size": "1024x1024"
}{- "created": 1677652288,
}Send chat request using Anthropic Messages API format.
Routes to providers that support the Anthropic format.
Supports web search plugins, file attachments, and provider routing preferences
(same as /chat/completions).
Streaming (stream: true) returns a Server-Sent Events stream of standard
Anthropic events. Router-added data rides as extra top-level fields on the
message_delta event — x_0g_trace, plus annotations when the web search
plugin was used — so every data: payload the router authors stays a valid
Anthropic stream event. Read them from the last message_delta; there can
be more than one, and only the last carries them. x_0g_trace is omitted
entirely when the router could not attach it to a valid message_delta, so
treat its absence as "not available", not as an error. message_stop is the
final frame whenever the provider sends one. Some clients strip unknown fields
from their parsed event objects, so read the raw SSE payload if your SDK does.
Non-streaming responses carry x_0g_trace at the top level of the response
body instead.
| X-0G-Provider-Address | string Routing: pin to a specific provider by on-chain address (0x-prefixed). |
| X-0G-Provider-Sort | string Routing: provider sort strategy. |
| X-0G-Provider-Trust-Mode | string Routing: trust tier filter ( |
| X-0G-Provider-Allow-Fallbacks | string Routing: whether to retry on other providers after a failure. |
| X-0G-Provider-Allow | string Routing: only these providers, comma-separated: |
| X-0G-Provider-Block | string Routing: never these providers, same forms as X-0G-Provider-Allow. Adds to the API key's own blocked providers. [beta] |
Anthropic Messages request
Array of objects (github_com_0glabs_0g-router_pkg_inference.Attachment) | |
| max_tokens | integer |
| messages | Array of any AnthropicMessage objects |
| metadata | any |
| model | string |
Array of objects (github_com_0glabs_0g-router_pkg_inference.Plugin) 0G Router extensions (stripped before forwarding) | |
object (github_com_0glabs_0g-router_pkg_inference.ProviderPreferences) | |
| stop_sequences | Array of strings |
| stream | boolean |
| system | any string or []AnthropicContentBlock |
| temperature | number |
| tool_choice | any |
| tools | Array of any |
| top_k | integer |
| top_p | number |
{- "attachments": [
- {
- "file_id": "file-abc123"
}
], - "max_tokens": 0,
- "messages": [
- null
], - "metadata": null,
- "model": "string",
- "plugins": [
- {
- "id": "web"
}
], - "provider": {
- "address": "0x1234...",
- "allow_fallbacks": true,
- "sort": "latency",
- "trust_mode": "verified"
}, - "stop_sequences": [
- "string"
], - "stream": true,
- "system": null,
- "temperature": 0,
- "tool_choice": null,
- "tools": [
- null
], - "top_k": 0,
- "top_p": 0
}{- "content": [
- {
- "id": "string",
- "input": null,
- "name": "string",
- "text": "string",
- "type": "string"
}
], - "id": "string",
- "model": "string",
- "role": "string",
- "stop_reason": "string",
- "type": "string",
- "usage": {
- "cache_creation": {
- "ephemeral_1h_input_tokens": 0,
- "ephemeral_5m_input_tokens": 0
}, - "cache_creation_input_tokens": 0,
- "cache_read_input_tokens": 0,
- "input_tokens": 0,
- "output_tokens": 0,
- "server_tool_use": {
- "web_search_requests": 0
}
}
}Send a request in OpenAI Responses API format (what OpenAI Codex speaks). [beta]
Routes only to providers that serve the Responses API for the model; a model with none returns 400 model_format_mismatch.
Stateless: previous_response_id, conversation, background and store: true are refused with a 400 — send the full input on every request. store defaults to false.
plugins and attachments are not supported on this endpoint.
Streaming (stream: true) returns the standard Responses event stream; x_0g_trace rides as an extra top-level field on the terminal response.completed (or response.incomplete / response.failed) event. Non-streaming responses carry it at the top level of the body.
| X-0G-Provider-Address | string Routing: pin to a specific provider by on-chain address (0x-prefixed). |
| X-0G-Provider-Sort | string Routing: provider sort strategy. |
| X-0G-Provider-Allow-Fallbacks | string Routing: whether to retry on other providers after a failure. |
| X-0G-Provider-Allow | string Routing: only these providers, comma-separated: |
| X-0G-Provider-Block | string Routing: never these providers, same forms as X-0G-Provider-Allow. Adds to the API key's own blocked providers. [beta] |
Responses API request
{ }{ }Return, in fallback order, the provider(s) the router WOULD select for a request — WITHOUT executing or billing (a pinned address with several upstreams and no X-0G-Provider-Identity does advance the internal round-robin counter). Built for end-to-end-encrypted (sealed) requests: a sealed request must be encrypted to a specific provider enclave before it can be sent, so a gateway calls this first (with the sensitive messages / prompt stripped out), seals to the head candidate, and pins the real request to it via X-0G-Provider-Address + X-0G-Provider-Identity — falling back to the next candidate (re-sealing) on failure.
The body is the stripped inference request plus the control field service_type — the internal service type being previewed (chatbot | text-to-image | image-editing | speech-to-text | embedding | decisions). This is the SAME vocabulary returned by GET /v1/service-types (.type) and accepted by GET /v1/providers (?service_type=), so a caller discovering providers via the catalog feeds the same string straight in (it is NOT the model-modality type on /v1/models). anthropic-chat is not an accepted service_type — the API surface is a separate axis, see api_format. api_format is OPTIONAL and applies to service_type=chatbot only, which is the one service type serving two surfaces: anthropic previews /v1/messages (candidates are narrowed to providers advertising the Anthropic format), openai previews /v1/chat/completions (candidates are narrowed to providers advertising the OpenAI format, as that endpoint routes), and omitting it previews either. A model with no provider on the requested surface is a 400 with code model_format_mismatch. Sending api_format with a non-chat service_type is a 400: image, audio, embedding and decisions have one surface each. embedding is accepted only where /v1/embeddings is served, decisions only where /v1/decisions is. model is OPTIONAL: given, candidates are that model's providers; omitted, candidates are ANY provider of the service type (a heterogeneous list — each candidate carries its own canonical_id / model_id). Routing preferences (provider / X-0G-Provider-*) and capability signals (tools, response_format, max_tokens, reasoning_effort) are read from the body/headers exactly as on the inference endpoints, so the previewed order matches what the request would select. The number of candidates is fixed at the router's provider-retry budget (the length of the fallback chain the router itself would try); a smaller healthy pool returns fewer. Each candidate returns the provider address and provider_identity (together, the pin — see below), its broker endpoint (to fetch the enclave key from), and the model it serves (canonical_id to put in the sealed request, model_id informational). provider_identity names the upstream a provider forwards to, and is present whenever that provider reports one — omitted otherwise, which is a property of the provider, not a promise that it serves only one upstream. Treat it as opaque: pin back exactly what the candidate carries (X-0G-Provider-Identity alongside X-0G-Provider-Address), including pinning nothing when it carries nothing, and infer nothing from its absence. Pin only the address where a candidate has an identity and the router re-picks among that address's upstreams at execute time, so you may be served by one other than the candidate you previewed and sealed against. A pinned provider.address returns just that provider. For the multipart inference endpoints (image-editing, speech-to-text) there is no JSON body to strip: synthesize this JSON body carrying service_type + model and forward routing prefs via X-0G-Provider-* headers — the uploaded blob (file / mask) and prompt need not (and should not) be included, as they are both sensitive and irrelevant to provider selection. [beta]
Preview request (stripped inference body + service_type/model)
| api_format | string OPTIONAL, chatbot only: openai | anthropic; empty = any format |
| auto | object Auto is required, and read only, when model is "0g/auto": the task to choose a model for, and constraints on the choice. [beta] Kept raw and decoded only for "0g/auto" with the feature on, so the field is ignored otherwise, as it was before it existed. |
| model | string OPTIONAL: canonical id (or alias / on-chain id); empty = any provider of this service type |
| service_type | string chatbot | text-to-image | image-editing | speech-to-text | embedding | decisions |
{- "api_format": "string",
- "auto": { },
- "model": "string",
- "service_type": "string"
}{- "auto": {
- "enabled": true,
- "model": "string",
- "task": "string"
}, - "encrypted_transit": "preferred",
- "object": "string",
- "providers": [
- {
- "address": "string",
- "canonical_id": "string",
- "endpoint": "string",
- "model_id": "string",
- "provider_identity": "aliyun"
}
], - "service_type": "string"
}Return this account's video jobs, most recent first. It exists so a client that lost a job id — a script that died after POST /videos returned, a page reloaded before the id was stored — can find it again: without it a lost id is a lost video, since every other video endpoint is keyed on the id.
Each entry is the ROUTER's record of the job, not the provider's video object: id (send it back to GET /videos/{id} unmodified), model, created_at (unix seconds, submit time), and the seconds / size the request asked for — seconds is quoted as a string and size echoes what you sent (1080p), not the provider's rendered resolution. Both are the values you REQUESTED and can differ from what was rendered and billed — a model that declares no seconds range may clamp the duration, and a model may downgrade a resolution it does not serve, so a request for 1080p can be delivered at 720p while this still shows 1080p. GET /videos/{id} reports what the provider actually produced. Fields the provider owns, such as progress, are absent; a job still running has them there too. status is in_progress | completed | failed, derived from the router's own record — completed means the clip was delivered AND charged, and in_progress includes a clip the provider may already have finished but nobody has polled for yet. Poll GET /videos/{id} for the provider's full object; that is also what settles the charge.
Only jobs submitted through this router are visible, and only your own. The window is the most recent 100 jobs — there is no cursor, so an id lost further back than that cannot be recovered here.
A listed job is a router-side RECORD, not a guarantee the file still exists: the media is held by the model provider, not by this router, and vendors expire it (roughly a day to a week depending on the vendor). So status: completed on an older entry can still mean GET /videos/{id}/content no longer has anything to serve.
| limit | integer How many jobs to return, most recent first. Default 20, maximum 100 — a larger value is clamped, not rejected. There is no pagination: only the most recent 100 jobs are reachable. |
{ }Submit a video generation job (OpenAI Video API shape). The response id names the provider that owns the job, so poll it at GET /videos/{id} and download from GET /videos/{id}/content with no other parameter. Store it as text — it is up to 80 characters, not the 36 the older format used — and send it back exactly as returned. provider_address is still accepted but is ignored when the id names one.
Accepts application/json OR multipart/form-data. Use multipart to drive image-to-video: send the same fields as form values plus the reference image as a file part.
Supports provider routing preferences via X-0G-Provider-* request headers (Address, Sort, Trust-Mode, Allow-Fallbacks), identical to the other inference endpoints.
The request shape is the OpenAI Video API's, but the models behind it are not OpenAI's, and where a model's own limits differ from OpenAI's they win. Those limits are per-model — read them from the model's description and pricing.variants on GET /v1/models rather than assuming the OpenAI defaults — and a request that violates one is rejected by the model provider, so the error text and any numeric code in it are theirs, not ours. The two that differ most often are size and seconds.
size names a resolution TIER, not output dimensions, because a video model advertises the tiers it is PRICED at rather than arbitrary sizes. Two spellings are accepted and they are not equivalent. Pixel dimensions (1280x720, OpenAI's spelling and what an SDK sends) select the ASPECT RATIO only, and only for text-to-video — the clip renders at whatever tier the model serves, so on a 2K-only model 1280x720 returns a 2560x1440 clip billed at the 2K rate, not a 720p one. For image-to-video the aspect ratio follows your reference image, so pixel dimensions have no effect there — a tier name still selects the tier. A tier name (2K) addresses the tier directly. Send only names that appear in that list — it is the set this endpoint can price, and it grows as a model adds tiers, so read it rather than hard-coding what a model serves today. For a model whose video_capabilities lists a resolution control, any other tier name is refused with 400 (the message lists the tiers) instead of rendering at a different tier. Read the tiers from pricing.variants[].dimensions.resolution. Omitting size is the recommended default — the model's own default tier and aspect ratio apply.
seconds must lie within the model's supported range. For a model with a known range (MiniMax-H3 4–15, ByteDance Seedance 2.5 4–30, Seedance 2.0 4–15; shown as the seconds control in video_capabilities on GET /v1/models when that model's vendor fields are available), a request outside it is rejected with 400 before anything is generated or charged, and the error states the range. For a model with no known range, the provider may clamp an out-of-range value without an error, and you are billed for the clip actually produced. Video edit is the one exception: a model whose seconds control lists auto_with: ["reference_video"] (Seedance 2.5) takes the length from the reference video, so with a reference_video in metadata.content send seconds: -1 or leave seconds out.
For both fields the submit response echoes what you SENT, while the poll response reports what was actually rendered. Reconcile against the poll.
[beta] A model whose GET /v1/models entry lists video_capabilities also accepts the vendor's own fields (first/last frame, reference images/video/audio, and the controls listed there) under metadata, forwarded unchanged. Such a request is routed only to an endpoint that forwards metadata, and is rejected with 400 model_not_capable rather than having those fields dropped; send it as JSON, not multipart.
| X-0G-Provider-Address | string Routing: pin to a specific provider by on-chain address (0x-prefixed). |
| X-0G-Provider-Sort | string Routing: provider sort strategy. |
| X-0G-Provider-Trust-Mode | string Routing: trust tier filter ( |
| X-0G-Provider-Allow-Fallbacks | string Routing: whether to retry on other providers after a failure. |
| X-0G-Provider-Allow | string Routing: only these providers, comma-separated: |
| X-0G-Provider-Block | string Routing: never these providers, same forms as X-0G-Provider-Allow. Adds to the API key's own blocked providers. [beta] |
Video generation request. model, prompt and seconds are REQUIRED (seconds is optional in the upstream OpenAI Video API but mandatory here — see the changelog); size is optional.
{ }{ }Return a video job's current status. When the job has completed this is also what settles the charge. provider_address is optional — it is resolved from the job id when omitted, so an OpenAI-native client can call GET /videos/{id} with no query parameters.
The object is the model provider's, passed through: beyond the fields this router sets (id, x_0g_trace on completion, and seconds / size from your request when the provider omits them), a field appears only when the provider reports it — in particular expires_at is present only when the provider states how long it keeps the clip; absent means unknown, not a default. The clip lives with the provider: once it is gone, GET /videos/{id}/content no longer returns it.
| id required | string Video job id exactly as returned by POST /videos. It names the provider that owns the job, so it is longer than the provider's own id (up to 80 chars) — store it as text and echo it back unmodified. Ids issued before this became the format keep working. |
| provider_address | string Pin the provider, for an id issued before ids named their own provider. Ignored when the id names one. |
| verify_tee | boolean Verify the provider's TEE signature and include the trace |
{ }[beta] Every file a completed video job produced — the clip, and anything else the request asked the model for (for example the last frame, with metadata.return_last_frame) — each with a content_url to download it from. Available for videos served by an endpoint that forwards vendor-native fields (see video_capabilities on GET /models); other videos return 404 artifact_not_found and have only GET /videos/{id}/content. Same rules as /content: a job not yet charged is charged first, a running job returns 409.
| id required | string Video job id exactly as returned by POST /videos |
| provider_address | string Pin the provider, for an id issued before ids named their own provider. Ignored when the id names one. |
{ }[beta] Stream one file listed by GET /videos/{id}/artifacts. Same rules as /content.
| id required | string Video job id exactly as returned by POST /videos |
| key required | string Artifact key, as listed by GET /videos/{id}/artifacts |
| provider_address | string Pin the provider, for an id issued before ids named their own provider. Ignored when the id names one. |
Stream the finished video file. If the job has not been charged yet (the client never polled GET /videos/{id}) it is charged before any bytes are sent. A job that is still running returns 409; a job that failed at the provider returns 424. provider_address is optional: an id issued by POST /videos names its own provider, and an older id is resolved by lookup.
| id required | string Video job id exactly as returned by POST /videos. It names the provider that owns the job, so it is longer than the provider's own id (up to 80 chars) — store it as text and echo it back unmodified. Ids issued before this became the format keep working. |
| provider_address | string Pin the provider, for an id issued before ids named their own provider. Ignored when the id names one. |
| verify_tee | boolean Verify the provider's TEE signature before billing |
Runs one web search and returns the results, for a client that executes a search tool itself: declare a web_search function tool, and when the model calls it, run its query here and send the results back as the tool result. This works with every model that supports tool calling, including end-to-end-encrypted ones, whose prompt the router cannot add search results to; only the query leaves the encrypted conversation.
Billed at the per-search fee when results are returned (in 0G for 0G-settled accounts, converted at the router's current rate); a search with no results is free. Counts toward the inference rate limit. [beta]
Search query
| query | string Query is the search query, 1–400 characters. |
{- "query": "latest stable Python release"
}{- "query": "string",
- "results": [
- {
- "content": "string",
- "published_date": "2026-09-30",
- "title": "Python 3.14.8",
}
], - "x_0g_trace": {
- "billing": {
- "currency": "usd",
- "total_cost": "20000",
- "web_search_cost": "20000"
}, - "request_id": "string"
}
}Get all available AI models. By default the response is the canonical view: one row per canonical_id, with curated registry metadata and endpoints aggregated (max context, union of params/formats, cheapest pricing); id is the canonical model id. A model stays listed even when all its endpoints are temporarily unhealthy (health is not a visibility filter; routing falls back to unhealthy endpoints so a listed model is always routable). To enumerate the endpoints behind a canonical id, call GET /v1/providers?canonical_id=<id>. provider_address uses OR (match any), input_modality and supported_parameter use AND (must match all).
?legacy=true returns the historical view keyed by the raw provider model_id (one row per on-chain model id, including ids not mapped to a registered canonical), for clients that have not migrated to canonical ids. This is a listing-only compatibility surface — routing remains canonical-only, so a raw id absent from the model registry is still 404 model_not_found on the inference path. [beta]
| legacy | boolean [beta] true: historical raw-model_id-keyed view (listing-only; an unregistered id it lists is still 404 on the inference path). Default false: canonical view (id = canonical_id). |
| pricing | string Value: "usd" [beta] 'usd': emit the OpenRouter-standard shape with per-token USD decimal strings under the top-level |
| provider_address | Array of strings Filter by provider address (OR: match any) |
| input_modality | Array of strings Filter by input modality, e.g. text, image (AND: must support all) |
| supported_parameter | Array of strings Filter by supported parameter, e.g. temperature (AND: must support all) |
{- "data": [
- {
- "architecture": {
- "input_modalities": [
- "string"
], - "instruct_type": "string",
- "max_input_bytes": {
- "property1": 0,
- "property2": 0
}, - "modality": "string",
- "output_modalities": [
- "string"
], - "tokenizer": "string",
- "url_input_modalities": [
- "string"
]
}, - "async_supported": true,
- "context_length": 0,
- "created": 1737936000,
- "default_parameters": {
- "property1": null,
- "property2": null
}, - "description": "string",
- "e2ee": "string",
- "expiration_date": "string",
- "id": "qwen-2.5-7b-instruct",
- "image_capabilities": {
- "controls": [
- {
- "default": "string",
- "key": "seed",
- "max": 0,
- "max_length": 16,
- "min": 0,
- "note": "string",
- "path": "seed",
- "type": "integer",
- "values": [
- "string"
]
}
], - "max_n": 1,
- "multi_turn": {
- "history_field": "messages",
- "response_field": "assembled_history",
- "session_field": "session"
}, - "references": {
- "accepts": [
- "url"
], - "endpoint": "/v1/images/generations",
- "fields": [
- "image"
], - "max": 3
}, - "size": {
- "default": "2048x2048",
- "max_pixels": 1048576,
- "max_side": 2048,
- "min_pixels": 3686400,
- "min_side": 512,
- "note": "string",
- "sizes": [
- "1024x1024",
- "1280x720"
]
}
}, - "input_capabilities": {
- "property1": {
- "accepts": [
- "base64",
- "url"
], - "max_bytes": 10485760
}, - "property2": {
- "accepts": [
- "base64",
- "url"
], - "max_bytes": 10485760
}
}, - "max_completion_tokens": 0,
- "name": "string",
- "object": "model",
- "owned_by": "0G Foundation",
- "pricing": {
- "cache_write": "string",
- "cache_write_1h": "string",
- "cached_prompt": "string",
- "completion": "string",
- "image": "string",
- "modality_pricing": {
- "input": {
- "property1": "string",
- "property2": "string"
}, - "output": {
- "property1": "string",
- "property2": "string"
}
}, - "prompt": "string",
- "tiered_pricing": [
- {
- "cached_prompt": "string",
- "completion": "string",
- "max_input_tokens": 0,
- "prompt": "string"
}
], - "variants": [
- {
- "dimensions": {
- "property1": "string",
- "property2": "string"
}, - "unit": "string",
- "unit_price": "string"
}
], - "video": "string",
- "video_unit": "string"
}, - "pricing_usd": {
- "cache_write": "string",
- "cache_write_1h": "string",
- "cached_prompt": "string",
- "completion": "string",
- "image": "string",
- "modality_pricing": {
- "input": {
- "property1": "string",
- "property2": "string"
}, - "output": {
- "property1": "string",
- "property2": "string"
}
}, - "prompt": "string",
- "tiered_pricing": [
- {
- "cached_prompt": "string",
- "completion": "string",
- "max_input_tokens": 0,
- "prompt": "string"
}
], - "variants": [
- {
- "dimensions": {
- "property1": "string",
- "property2": "string"
}, - "unit": "string",
- "unit_price": "string"
}
], - "video": "string",
- "video_unit": "string"
}, - "provider_count": 0,
- "speech_capabilities": {
- "controls": [
- {
- "default": "string",
- "exclusive_min": true,
- "key": "emotion",
- "max": 0,
- "min": 0,
- "note": "string",
- "type": "enum",
- "values": [
- "string"
]
}
], - "max_input_bytes": 2000,
- "response_formats": [
- "mp3",
- "wav"
], - "speed": {
- "max": 2,
- "min": 0.5
}, - "voices": [
- {
- "id": "English_Graceful_Lady",
- "language": "English",
- "name": "Graceful Lady"
}
], - "voices_note": "string"
}, - "supported_formats": [
- "string"
], - "supported_parameters": [
- "string"
], - "tee_attested": true,
- "tee_type": "string",
- "tee_verifier": "string",
- "type": "string",
- "verifiability": "string",
- "video_capabilities": {
- "property1": null,
- "property2": null
}
}
], - "object": "list"
}Get all TEE-acknowledged providers, optionally narrowed by service type, on-chain model id, and/or canonical id. model and canonical_id are independent filters and compose (ANDed): canonical_id alone lists every endpoint of a canonical, while model + canonical_id narrows to a specific endpoint within it. An empty value means "not filtered on" (so no filters = list all). Includes providers with unknown health status (is_healthy=null).
| service_type | string Filter by service type (chatbot, text-to-image, speech-to-text) |
| model | string Filter by on-chain model ID (e.g. zai-org/GLM-5.1-FP8); exact model_id match. Empty = not filtered. |
| canonical_id | string [beta] Filter by canonical model ID (e.g. glm-5.1); lists every endpoint serving that canonical. Composes (AND) with model. Empty = not filtered. |
{- "data": [
- {
- "address": "0x1234567890abcdef",
- "architecture": {
- "input_modalities": [
- "string"
], - "instruct_type": "string",
- "max_input_bytes": {
- "property1": 0,
- "property2": 0
}, - "modality": "string",
- "output_modalities": [
- "string"
], - "tokenizer": "string",
- "url_input_modalities": [
- "string"
]
}, - "canonical_id": "glm-5.1",
- "context_length": 0,
- "default_parameters": {
- "property1": null,
- "property2": null
}, - "expiration_date": "string",
- "is_healthy": true,
- "latency": 150,
- "max_completion_tokens": 0,
- "model_id": "qwen-2.5-7b-instruct",
- "name": "string",
- "pricing": {
- "cache_write": "string",
- "cache_write_1h": "string",
- "cached_prompt": "string",
- "completion": "string",
- "image": "string",
- "modality_pricing": {
- "input": {
- "property1": "string",
- "property2": "string"
}, - "output": {
- "property1": "string",
- "property2": "string"
}
}, - "prompt": "string",
- "tiered_pricing": [
- {
- "cached_prompt": "string",
- "completion": "string",
- "max_input_tokens": 0,
- "prompt": "string"
}
], - "variants": [
- {
- "dimensions": {
- "property1": "string",
- "property2": "string"
}, - "unit": "string",
- "unit_price": "string"
}
], - "video": "string",
- "video_unit": "string"
}, - "pricing_usd": {
- "cache_write": "string",
- "cache_write_1h": "string",
- "cached_prompt": "string",
- "completion": "string",
- "image": "string",
- "modality_pricing": {
- "input": {
- "property1": "string",
- "property2": "string"
}, - "output": {
- "property1": "string",
- "property2": "string"
}
}, - "prompt": "string",
- "tiered_pricing": [
- {
- "cached_prompt": "string",
- "completion": "string",
- "max_input_tokens": 0,
- "prompt": "string"
}
], - "variants": [
- {
- "dimensions": {
- "property1": "string",
- "property2": "string"
}, - "unit": "string",
- "unit_price": "string"
}
], - "video": "string",
- "video_unit": "string"
}, - "provider_country": "string",
- "provider_identity": "aliyun",
- "provider_name": "string",
- "service_type": "chatbot",
- "serving_domain": "string",
- "supported_formats": [
- "string"
], - "supported_parameters": [
- "string"
], - "tee_acknowledged": true,
- "tee_attested": true,
- "tee_type": "string",
- "tee_verifier": "string",
- "trust_mode": "string",
- "type": "string",
- "uptime": 99.5,
- "verifiability": "string"
}
], - "object": "list"
}Get service types that have at least one TEE-acknowledged provider (health is not a filter — a service type stays listed even when its providers are temporarily unhealthy)
{- "data": [
- {
- "label": "Chat",
- "provider_count": 3,
- "type": "chatbot"
}
], - "object": "list"
}