0G Router API (2.0)

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.

Balance model: Router ledger vs Payment Layer vault

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.

Picking an endpoint: /balance vs /funds

If 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.

Admission rule

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, or
  • deposit + 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.

Auto-pull from the vault (mainnet values)

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.

Predicting "can submit" on the client

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.

Request IDs and reconciliation

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.

Changelog

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].

v2.0 — 2026-11

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.
  • Request field names are read in lower case only (all inference 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.
  • Image and video requests outside a model's published limits return 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.
  • Errors from model providers arrive in the endpoint's own envelope: {"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.
  • The 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.
  • An unknown model id is 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

  • Async video [beta] — 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.
  • The 0G Pay refusal codes are under Billing and balances; the in-stream codes 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.
  • Job ids have the form 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.
  • Billing happens at completion, on the duration actually delivered (your 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.
  • How many jobs you can run: each unfinished job reserves its cost (its duration at the model's dearest rate), and a submit is admitted when everything running plus it fits your spendable balance (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.
  • Re-polls carry 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.
  • Account types: a USD account can use a model only when it publishes a USD video price (else 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

  • Added: ByteDance Seedance 2.5, 2.0, 2.0 Fast and 2.0 Mini (video); -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.
  • Model ids accept . 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".
  • Image pricing [beta]: a model priced by output size lists its tiers in 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.
  • Image input: a chat request with an image part is routed only to upstreams that declare image input (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.
  • What is billed: /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.
  • 0G accounts: admission counts deposit + credit − amount owed, plus your Payment Layer balance, of which 80% now counts (was 50%). See Predicting "can submit" on the client above.
  • USD accounts billed by 0G Pay: /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.
  • USD routing skips endpoints with no USD price instead of taking the whole model offline; 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.
  • Streaming with 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.
  • Fees: the web plugin may charge a per-search fee, reported in 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.
  • The web plugin reads message content given as an array, and results state the retrieval date and each source's publication date.

Streaming and limits

  • The maximum streaming duration rose from 10 to 59 minutes. At the limit a stream ends with an error event, code 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.
  • A non-streaming request may run up to 20 minutes (was about 9.5).
  • Every 429 from a provider carries Retry-After (the provider's own, else 5 s).
  • The request body cap on chat-tier endpoints rose from 16 MB to 20 MB.

Routing

  • Pinning: 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).
  • A request gets up to 4 provider attempts (was 3) and never retries an upstream that just rejected it through another address.
  • /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.
  • Requests to providers carry the router's own User-Agent (0g-router).

/v1/messages errors

  • Every error the router itself returns is in the Anthropic envelope and carries 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]

  • For 0G Private Computer clients. Seal the private fields into a top-level _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.
  • Find the enclave with POST /v1/routing/preview and pin both X-0G-Provider-Address and X-0G-Provider-Identity; when falling back, re-seal for each candidate.
  • Billing reads cleartext counts: 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.
  • Refused with 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.
  • Documentation: GET /v1/account/balance is now listed in this reference, and the size / seconds behaviour of video models is documented.

Account

Get account

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.

Authorizations:
ManagementKeyAuth

Responses

Response samples

Content type
application/json
{
  • "address": "0x15d34AAf54267DB7D7c367839AAf71A00a2C6A65",
  • "created_at": "2026-01-15T10:30:00Z",
  • "og_mode_available": true,
  • "onboarded_at": "2026-01-15T10:35:00Z"
}

Get account balance

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.

Authorizations:
ManagementKeyAuth

Responses

Response samples

Content type
application/json
{
  • "address": "0x15d34AAf54267DB7D7c367839AAf71A00a2C6A65",
  • "balance": "1000000000000000000",
  • "credit_balance": "100000000000000000",
  • "currency": "0g",
  • "deposit_balance": "900000000000000000",
  • "pending_charge": "0",
  • "total_balance": "1000000000000000000",
  • "unsettled_charge": "87"
}

Get unified account funds

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.

Authorizations:
ManagementKeyAuth

Responses

Response samples

Content type
application/json
{
  • "address": "0x15d34AAf54267DB7D7c367839AAf71A00a2C6A65",
  • "currency": "0g",
  • "payment_layer": {
    },
  • "router": {
    },
  • "total": "7390000000000000000"
}

Get account routing rules

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]

Authorizations:
ManagementKeyAuth

Responses

Response samples

Content type
application/json
{
  • "allow_fallbacks": true,
  • "allowed_models": [
    ],
  • "allowed_providers": [
    ],
  • "blocked_models": [
    ],
  • "blocked_providers": [
    ],
  • "encrypted_transit": "required",
  • "max_price_usd": {
    },
  • "require_parameters": false,
  • "sort": "price",
  • "trust_mode": "verified",
  • "updated_at": "2026-11-02T08:00:00Z",
  • "warnings": [
    ]
}

Replace account routing rules

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]

Authorizations:
ManagementKeyAuth
Request Body schema: application/json
required

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).

Responses

Request samples

Content type
application/json
{
  • "allow_fallbacks": true,
  • "allowed_models": [
    ],
  • "allowed_providers": [
    ],
  • "blocked_models": [
    ],
  • "blocked_providers": [
    ],
  • "encrypted_transit": "required",
  • "max_price_usd": {
    },
  • "require_parameters": false,
  • "sort": "price",
  • "trust_mode": "verified"
}

Response samples

Content type
application/json
{
  • "allow_fallbacks": true,
  • "allowed_models": [
    ],
  • "allowed_providers": [
    ],
  • "blocked_models": [
    ],
  • "blocked_providers": [
    ],
  • "encrypted_transit": "required",
  • "max_price_usd": {
    },
  • "require_parameters": false,
  • "sort": "price",
  • "trust_mode": "verified",
  • "updated_at": "2026-11-02T08:00:00Z",
  • "warnings": [
    ]
}

Explain routing under routing rules

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]

Authorizations:
ManagementKeyAuth
Request Body schema: application/json
required

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.

Responses

Request samples

Content type
application/json
{
  • "account_routing": {
    },
  • "api_format": "openai",
  • "api_key_id": "3f2a6c1e-8d4b-4f0a-9c7e-1b2d3e4f5a6b",
  • "api_key_routing": {
    },
  • "model": "glm-5.3",
  • "service_type": "chatbot"
}

Response samples

Content type
application/json
{
  • "allow_fallbacks": true,
  • "canonical_id": "glm-5.3",
  • "encrypted_transit": "preferred",
  • "max_attempts": 4,
  • "model": "glm-5.3",
  • "object": "routing.explanation",
  • "outcome": {
    },
  • "providers": [
    ],
  • "routable": 4,
  • "rule_sources": {
    },
  • "service_type": "chatbot",
  • "settlement": "0g",
  • "sort": "price",
  • "total": 6
}

Get daily usage statistics

Get usage statistics broken down by day for current user, with optional filters

Authorizations:
ManagementKeyAuth
query Parameters
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 dimensions=trust_mode to split each day/model row per trust tier and emit the trust_mode field. Omit (default) for the legacy one-row-per (date, model) shape.

Responses

Response samples

Content type
application/json
{
  • "currency": "0g",
  • "data": [
    ],
  • "object": "list"
}

Get usage history

Get usage history for current user, with optional filters

Authorizations:
ManagementKeyAuth
query Parameters
limit
integer
Default: 20

Limit number of records

offset
integer
Default: 0

Offset for pagination (legacy). Ignored when cursor is set.

cursor
string

[beta] Opaque keyset cursor from a prior page's next_cursor. When set, pages via seek (constant per-page cost, independent of depth) and offset is ignored; also forces include_total=false.

include_total
boolean
Default: true

[beta] Include the full-set total count (default true). Set false to skip the expensive COUNT(*); recommended with cursor.

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.

Responses

Response samples

Content type
application/json
{
  • "currency": "0g",
  • "data": [
    ],
  • "limit": 20,
  • "next_cursor": "string",
  • "object": "list",
  • "offset": 0,
  • "total": 100
}

Get usage statistics

Get usage statistics for current user, optionally filtered by API key and date range

Authorizations:
ManagementKeyAuth
query Parameters
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.

Responses

Response samples

Content type
application/json
{
  • "completion_tokens": 4345,
  • "currency": "0g",
  • "prompt_tokens": 8000,
  • "total_cost": "1000000000000000",
  • "total_requests": 42,
  • "total_tokens": 12345
}

List webhook endpoints

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]

Authorizations:
ManagementKeyAuth

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create a webhook endpoint

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]

Authorizations:
ManagementKeyAuth
Request Body schema: application/json
required

Endpoint

events
Array of strings
url
string

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "disabled_at": "string",
  • "events": [
    ],
  • "id": 12,
  • "last_delivery": {
    },
  • "previous_secret_expires_at": "string",
  • "secret": "whsec_9b1f…",
  • "status": "healthy",
}

Delete a webhook endpoint

Removes the endpoint and its delivery history; deliveries not yet sent are dropped. JWT, or a management key with webhooks:write. [beta]

Authorizations:
ManagementKeyAuth
path Parameters
id
required
integer

Endpoint id

Responses

List webhook deliveries

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]

Authorizations:
ManagementKeyAuth
path Parameters
id
required
integer

Endpoint id

query Parameters
before
integer

Cursor: deliveries older than this id

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "has_more": true,
  • "next_before": 0
}

Rotate a webhook signing secret

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]

Authorizations:
ManagementKeyAuth
path Parameters
id
required
integer

Endpoint id

Responses

Response samples

Content type
application/json
{
  • "previous_secret_expires_at": "string",
  • "secret": "whsec_9b1f…"
}

Send a test event

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]

Authorizations:
ManagementKeyAuth
path Parameters
id
required
integer

Endpoint id

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "event_id": "evt_4f1c2a9b0d3e5f6a7b8c9d0e",
  • "ok": true,
  • "status_code": 0,
  • "type": "balance.low"
}

API Key

Get API key list

Get all API keys for current user

Authorizations:
ManagementKeyAuth
query Parameters
status
string

Filter: active / revoked / expired / all (default all)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "object": "list"
}

Create API key

Create a new API key for LLM service access

Authorizations:
ManagementKeyAuth
Request Body schema: application/json

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".

Responses

Request samples

Content type
application/json
{
  • "allowed_models": [
    ],
  • "allowed_providers": [
    ],
  • "credit_limit": "string",
  • "expiration": "string",
  • "name": "string",
  • "reset_period": "string",
  • "routing": {
    },
  • "trust_mode": "string"
}

Response samples

Content type
application/json
{
  • "allowed_models": [
    ],
  • "allowed_providers": [
    ],
  • "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": {
    },
  • "status": "active",
  • "trust_mode": "verified",
  • "used": "0.42"
}

Revoke API key

Revoke a specific API key

Authorizations:
ManagementKeyAuth
path Parameters
keyId
required
string

API Key ID

Responses

Response samples

Content type
application/json
{
  • "key_id": "abc12345",
  • "message": "API key revoked"
}

Update API key

Update name / credit_limit / reset_period / expiration of an API key

Authorizations:
ManagementKeyAuth
path Parameters
keyId
required
string

API Key ID

Request Body schema: application/json
required

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.

Responses

Request samples

Content type
application/json
{
  • "allowed_models": [
    ],
  • "allowed_providers": [
    ],
  • "credit_limit": "string",
  • "expiration": "string",
  • "name": "string",
  • "reset_period": "string",
  • "trust_mode": "string"
}

Response samples

Content type
application/json
{
  • "allowed_models": [
    ],
  • "allowed_providers": [
    ],
  • "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": {
    },
  • "status": "active",
  • "trust_mode": "verified",
  • "used": "0.42"
}

Get API key routing rules

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]

Authorizations:
ManagementKeyAuth
path Parameters
keyId
required
string

API Key ID

Responses

Response samples

Content type
application/json
{
  • "allow_fallbacks": true,
  • "allowed_models": [
    ],
  • "allowed_providers": [
    ],
  • "blocked_models": [
    ],
  • "blocked_providers": [
    ],
  • "encrypted_transit": "required",
  • "key_id": "3f2a6c1e-8d4b-4f0a-9c7e-1b2d3e4f5a6b",
  • "max_price_usd": {
    },
  • "require_parameters": false,
  • "sort": "price",
  • "trust_mode": "verified",
  • "warnings": [
    ]
}

Replace API key routing rules

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]

Authorizations:
ManagementKeyAuth
path Parameters
keyId
required
string

API Key ID

Request Body schema: application/json
required

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).

Responses

Request samples

Content type
application/json
{
  • "allow_fallbacks": true,
  • "allowed_models": [
    ],
  • "allowed_providers": [
    ],
  • "blocked_models": [
    ],
  • "blocked_providers": [
    ],
  • "encrypted_transit": "required",
  • "max_price_usd": {
    },
  • "require_parameters": false,
  • "sort": "price",
  • "trust_mode": "verified"
}

Response samples

Content type
application/json
{
  • "allow_fallbacks": true,
  • "allowed_models": [
    ],
  • "allowed_providers": [
    ],
  • "blocked_models": [
    ],
  • "blocked_providers": [
    ],
  • "encrypted_transit": "required",
  • "key_id": "3f2a6c1e-8d4b-4f0a-9c7e-1b2d3e4f5a6b",
  • "max_price_usd": {
    },
  • "require_parameters": false,
  • "sort": "price",
  • "trust_mode": "verified",
  • "warnings": [
    ]
}

Inference

Submit async image edit job

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.

Authorizations:
ApiKeyAuth
header Parameters
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. latency | price.

X-0G-Provider-Trust-Mode
string

Routing: trust tier filter (verified | private). verified is a floor — private providers also satisfy it.

X-0G-Provider-Allow-Fallbacks
string

Routing: whether to retry on other providers after a failure. true | false. Defaults to false when an address is pinned, true otherwise.

X-0G-Provider-Allow
string

Routing: only these providers, comma-separated: 0x… (every upstream behind that address), 0x…/identity (one upstream behind it) or */identity (that upstream behind every address). Combines with the API key's own allowed providers: a provider must be on both. [beta]

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

Response samples

Content type
application/json
{ }

Submit async image generation job

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.

Authorizations:
ApiKeyAuth
header Parameters
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. latency | price.

X-0G-Provider-Trust-Mode
string

Routing: trust tier filter (verified | private). verified is a floor — private providers also satisfy it.

X-0G-Provider-Allow-Fallbacks
string

Routing: whether to retry on other providers after a failure. true | false. Defaults to false when an address is pinned, true otherwise.

X-0G-Provider-Allow
string

Routing: only these providers, comma-separated: 0x… (every upstream behind that address), 0x…/identity (one upstream behind it) or */identity (that upstream behind every address). Combines with the API key's own allowed providers: a provider must be on both. [beta]

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]

Request Body schema: application/json
required

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

Responses

Request samples

Content type
application/json
{
  • "model": "dall-e-3",
  • "n": 1,
  • "prompt": "A beautiful sunset",
  • "response_format": "url",
  • "size": "1024x1024"
}

Response samples

Content type
application/json
{ }

Create speech

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]

Authorizations:
ApiKeyAuth
header Parameters
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. true | false. Defaults to false when an address is pinned, true otherwise.

X-0G-Provider-Allow
string

Routing: only these providers, comma-separated: 0x… (every upstream behind that address), 0x…/identity (one upstream behind it) or */identity (that upstream behind every address). Combines with the API key's own allowed providers: a provider must be on both. [beta]

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]

Request Body schema: application/json
required

Speech request

input
string
model
string
response_format
string
speed
number
voice
string

Responses

Request samples

Content type
application/json
{
  • "input": "string",
  • "model": "string",
  • "response_format": "string",
  • "speed": 0,
  • "voice": "string"
}

Audio transcription

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.
Authorizations:
ApiKeyAuth
header Parameters
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. latency | price.

X-0G-Provider-Trust-Mode
string

Routing: trust tier filter (verified | private). verified is a floor — private providers also satisfy it.

X-0G-Provider-Allow-Fallbacks
string

Routing: whether to retry on other providers after a failure. true | false. Defaults to false when an address is pinned, true otherwise.

X-0G-Provider-Allow
string

Routing: only these providers, comma-separated: 0x… (every upstream behind that address), 0x…/identity (one upstream behind it) or */identity (that upstream behind every address). Combines with the API key's own allowed providers: a provider must be on both. [beta]

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]

Request Body schema:
required

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

Responses

Request samples

Content type
{
  • "file_base64": "SGVsbG8gd29ybGQ=",
  • "filename": "audio.mp3",
  • "language": "en",
  • "model": "whisper-1",
  • "response_format": "json"
}

Response samples

Content type
application/json
{
  • "duration": 5.5,
  • "language": "en",
  • "text": "Hello, world!"
}

Chat completion

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]

Authorizations:
ApiKeyAuth
header Parameters
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. latency | price.

X-0G-Provider-Trust-Mode
string

Routing: trust tier filter (verified | private). verified is a floor — private providers also satisfy it.

X-0G-Provider-Allow-Fallbacks
string

Routing: whether to retry on other providers after a failure. true | false. Defaults to false when an address is pinned, true otherwise.

X-0G-Provider-Allow
string

Routing: only these providers, comma-separated: 0x… (every upstream behind that address), 0x…/identity (one upstream behind it) or */identity (that upstream behind every address). Combines with the API key's own allowed providers: a provider must be on both. [beta]

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]

Request Body schema: application/json
required

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

Responses

Request samples

Content type
application/json
{
  • "attachments": [
    ],
  • "max_tokens": 1024,
  • "messages": [
    ],
  • "model": "qwen/qwen-2.5-7b-instruct",
  • "plugins": [
    ],
  • "provider": {
    },
  • "response_format": {
    },
  • "stream": false,
  • "temperature": 0.7,
  • "tool_choice": null,
  • "tools": [
    ],
  • "top_p": 0.9
}

Response samples

Content type
application/json
{
  • "choices": [
    ],
  • "created": 1677652288,
  • "id": "chatcmpl-123",
  • "model": "qwen/qwen-2.5-7b-instruct",
  • "object": "chat.completion",
  • "usage": {
    },
  • "x_0g_trace": {
    }
}

Create decisions

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]

Authorizations:
ApiKeyAuth
header Parameters
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. latency | price.

X-0G-Provider-Trust-Mode
string

Routing: trust tier filter (verified | private). verified is a floor — private providers also satisfy it.

X-0G-Provider-Allow-Fallbacks
string

Routing: whether to retry on other providers after a failure. true | false. Defaults to false when an address is pinned, true otherwise.

X-0G-Provider-Allow
string

Routing: only these providers, comma-separated: 0x… (every upstream behind that address), 0x…/identity (one upstream behind it) or */identity (that upstream behind every address). Combines with the API key's own allowed providers: a provider must be on both. [beta]

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]

Request Body schema: application/json
required

Decisions request

model
string

Model ID

questions
Array of integers

Named typed questions

state
Array of integers

App state the questions are asked about

Responses

Request samples

Content type
application/json
{
  • "model": "jev-1.13",
  • "questions": [
    ],
  • "state": [
    ]
}

Response samples

Content type
application/json
{ }

Create embeddings

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]

Authorizations:
ApiKeyAuth
header Parameters
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. latency | price.

X-0G-Provider-Trust-Mode
string

Routing: trust tier filter (verified | private). verified is a floor — private providers also satisfy it.

X-0G-Provider-Allow-Fallbacks
string

Routing: whether to retry on other providers after a failure. true | false. Defaults to false when an address is pinned, true otherwise.

X-0G-Provider-Allow
string

Routing: only these providers, comma-separated: 0x… (every upstream behind that address), 0x…/identity (one upstream behind it) or */identity (that upstream behind every address). Combines with the API key's own allowed providers: a provider must be on both. [beta]

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]

Request Body schema: application/json
required

Embedding request

input
Array of integers

Text (or array of texts / token arrays) to embed

model
string

Model ID

Responses

Request samples

Content type
application/json
{
  • "input": [
    ],
  • "model": "qwen3.7-text-embedding"
}

Response samples

Content type
application/json
{ }

Image editing

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.

Authorizations:
ApiKeyAuth
header Parameters
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. latency | price.

X-0G-Provider-Trust-Mode
string

Routing: trust tier filter (verified | private). verified is a floor — private providers also satisfy it.

X-0G-Provider-Allow-Fallbacks
string

Routing: whether to retry on other providers after a failure. true | false. Defaults to false when an address is pinned, true otherwise.

X-0G-Provider-Allow
string

Routing: only these providers, comma-separated: 0x… (every upstream behind that address), 0x…/identity (one upstream behind it) or */identity (that upstream behind every address). Combines with the API key's own allowed providers: a provider must be on both. [beta]

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]

Request Body schema: multipart/form-data
image
string <binary>

Source image file

prompt
required
string

Edit instruction

model
required
string

Model ID

Responses

Response samples

Content type
application/json
{
  • "created": 1677652288,
  • "data": [
    ]
}

Image generation

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.

Authorizations:
ApiKeyAuth
header Parameters
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. latency | price.

X-0G-Provider-Trust-Mode
string

Routing: trust tier filter (verified | private). verified is a floor — private providers also satisfy it.

X-0G-Provider-Allow-Fallbacks
string

Routing: whether to retry on other providers after a failure. true | false. Defaults to false when an address is pinned, true otherwise.

X-0G-Provider-Allow
string

Routing: only these providers, comma-separated: 0x… (every upstream behind that address), 0x…/identity (one upstream behind it) or */identity (that upstream behind every address). Combines with the API key's own allowed providers: a provider must be on both. [beta]

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]

Request Body schema: application/json
required

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

Responses

Request samples

Content type
application/json
{
  • "model": "dall-e-3",
  • "n": 1,
  • "prompt": "A beautiful sunset",
  • "response_format": "url",
  • "size": "1024x1024"
}

Response samples

Content type
application/json
{
  • "created": 1677652288,
  • "data": [
    ]
}

Anthropic Messages API

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.

Authorizations:
ApiKeyAuth
header Parameters
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. latency | price.

X-0G-Provider-Trust-Mode
string

Routing: trust tier filter (verified | private). verified is a floor — private providers also satisfy it.

X-0G-Provider-Allow-Fallbacks
string

Routing: whether to retry on other providers after a failure. true | false. Defaults to false when an address is pinned, true otherwise.

X-0G-Provider-Allow
string

Routing: only these providers, comma-separated: 0x… (every upstream behind that address), 0x…/identity (one upstream behind it) or */identity (that upstream behind every address). Combines with the API key's own allowed providers: a provider must be on both. [beta]

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]

Request Body schema: application/json
required

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

Responses

Request samples

Content type
application/json
{
  • "attachments": [
    ],
  • "max_tokens": 0,
  • "messages": [
    ],
  • "metadata": null,
  • "model": "string",
  • "plugins": [
    ],
  • "provider": {
    },
  • "stop_sequences": [
    ],
  • "stream": true,
  • "system": null,
  • "temperature": 0,
  • "tool_choice": null,
  • "tools": [
    ],
  • "top_k": 0,
  • "top_p": 0
}

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "id": "string",
  • "model": "string",
  • "role": "string",
  • "stop_reason": "string",
  • "type": "string",
  • "usage": {
    }
}

Responses API

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.

Authorizations:
ApiKeyAuth
header Parameters
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. latency | price.

X-0G-Provider-Allow-Fallbacks
string

Routing: whether to retry on other providers after a failure. true | false. Defaults to false when an address is pinned, true otherwise.

X-0G-Provider-Allow
string

Routing: only these providers, comma-separated: 0x… (every upstream behind that address), 0x…/identity (one upstream behind it) or */identity (that upstream behind every address). Combines with the API key's own allowed providers: a provider must be on both. [beta]

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]

Request Body schema: application/json
required

Responses API request

object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Preview provider selection (E2EE)

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]

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

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

Responses

Request samples

Content type
application/json
{
  • "api_format": "string",
  • "auto": { },
  • "model": "string",
  • "service_type": "string"
}

Response samples

Content type
application/json
{
  • "auto": {
    },
  • "encrypted_transit": "preferred",
  • "object": "string",
  • "providers": [
    ],
  • "service_type": "string"
}

List your video jobs

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.

Authorizations:
ApiKeyAuth
query Parameters
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.

Responses

Response samples

Content type
application/json
{ }

Submit async video generation job

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.

Authorizations:
ApiKeyAuth
header Parameters
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. latency | price.

X-0G-Provider-Trust-Mode
string

Routing: trust tier filter (verified | private). verified is a floor — private providers also satisfy it.

X-0G-Provider-Allow-Fallbacks
string

Routing: whether to retry on other providers after a failure. true | false. Defaults to false when an address is pinned, true otherwise.

X-0G-Provider-Allow
string

Routing: only these providers, comma-separated: 0x… (every upstream behind that address), 0x…/identity (one upstream behind it) or */identity (that upstream behind every address). Combines with the API key's own allowed providers: a provider must be on both. [beta]

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]

Request Body schema:
required

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.

object

Responses

Request samples

Content type
{ }

Response samples

Content type
application/json
{ }

Poll async video generation job

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.

Authorizations:
ApiKeyAuth
path Parameters
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.

query Parameters
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

Responses

Response samples

Content type
application/json
{ }

List a video's artifacts [beta]

[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.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Video job id exactly as returned by POST /videos

query Parameters
provider_address
string

Pin the provider, for an id issued before ids named their own provider. Ignored when the id names one.

Responses

Response samples

Content type
application/json
{ }

Download a video artifact [beta]

[beta] Stream one file listed by GET /videos/{id}/artifacts. Same rules as /content.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Video job id exactly as returned by POST /videos

key
required
string

Artifact key, as listed by GET /videos/{id}/artifacts

query Parameters
provider_address
string

Pin the provider, for an id issued before ids named their own provider. Ignored when the id names one.

Responses

Download a completed video

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.

Authorizations:
ApiKeyAuth
path Parameters
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.

query Parameters
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

Responses

Search the web

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]

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

Search query

query
string

Query is the search query, 1–400 characters.

Responses

Request samples

Content type
application/json
{
  • "query": "latest stable Python release"
}

Response samples

Content type
application/json
{
  • "query": "string",
  • "results": [],
  • "x_0g_trace": {
    }
}

Models

Get model list

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]

query Parameters
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 pricing field (for external pricing aggregators, e.g. TKX); models without a USD price are omitted. Default: native prices under pricing, USD under pricing_usd.

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)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "object": "list"
}

Provider

Get provider 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).

query Parameters
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.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "object": "list"
}

Service Types

Get available service types

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)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "object": "list"
}