Skip to main content
Ornn Inference serves models through offers. Each offer has an API format and separate prices for input, cached input, and output tokens. Open Models to compare offers and copy an API example. From shows the lowest price for each token type when offers differ. Open an offer to see its provider, API format, and exact prices. Compare shows published benchmark scores for models with results. Chat Completions offers also let you start a chat. Chat uses your signed-in organization and clears the conversation when you leave or refresh. Ornn Inference.

Run your first request

Set ORNN_API_KEY to a read-write key from the organization you want to use. Paid offers draw from that organization’s Ornn credits. Free offers can run with a zero balance. Create an API key · Credits and charges.
1

Find a model

List the available models. Each appears once in data. Save the model’s id.
2

Send a message

Replace publisher/model with the ID you saved. Ornn selects an active Chat Completions offer, using the lowest input price and then the lowest output price. If both prices tie, the lowest offer UUID wins.
The reply appears in choices[0].message.content.

Choose an API

Send the public model ID in model and match the endpoint to the API format.

Pin an offer

Use the listing filters to find an offer for the model and format. Prices are decimal strings in USD per million tokens. When the cached-input rate is null, the regular input rate applies.
Send the offer’s id in X-Ornn-Listing-Id to pin it. A top-level provider field requires a pin. Read one offer with GET /v1/listings/{listing_id}. To resolve provider names, pass listing provider_organization_id values to GET https://api.ornn.com/v1/organizations/inference-providers?ids=UUID,UUID. Publishers share a logo across models. Fetch it with GET /v1/publishers/{slug}/logo.

Cap token rates

By default, a generation request has no price ceilings. To limit what you pay per million tokens, send any of these headers. You can also pin an offer.
Rates at or below the ceiling qualify, including zero. Use a leading zero for fractions below one, such as 0.5. When an offer has no separate cached-input rate, Ornn uses its ordinary input rate to check the cached-input ceiling.
Use https://api.inference.ornn.com/v1 as the OpenAI SDK base URL. Use https://api.inference.ornn.com for the Anthropic SDK, which appends /v1/messages. To pin an offer, pass X-Ornn-Listing-Id as an extra header. Raw Messages requests accept x-api-key or a bearer token.Chat Completions, Responses, and Messages accept "stream": true. Use HTTP/2 when you need to cancel a streaming request promptly. With curl, --http2 requests HTTP/2 over HTTPS.Responses runs with store: false and supports function tools, custom tools, and web search. Send previous turns inline on follow-ups. Use inline content for Responses and Messages.Decisions takes input and one or more predicate, choice, or score questions. It returns answers and usage in one JSON response. All questions in a call count as one request at the offer’s token rates. Decisions request format.
  • 400 invalid_listing_id means the listing header is malformed or repeated.
  • 400 invalid_price_ceiling means a price ceiling is malformed or repeated.
  • 404 model_not_found means no available offer matches the model, format, any pin, and all supplied ceilings. Ornn returns this before starting or charging for the request.
  • 503 inference_pricing_unavailable means Ornn could not confirm pricing before starting generation. Try again shortly.
Each organization can send 30 generation requests per minute across its keys and Chat. If you get 429, wait for the delay in Retry-After before trying again. Model discovery and request history sit outside that allowance.Omit both filters from GET /v1/listings to see all available offers. Unknown or repeated filters and unsupported formats return 400 invalid_inference_listing_query.

CLI and MCP

The Ornn CLI uses your saved login or ORNN_API_KEY. Replace publisher/model with the public model ID. Add --listing-id to pin an offer.
For streaming completions, set "stream": true and use --format human to receive server-sent events. Press Ctrl-C to close the stream. Discover offers with ornn inference models list and ornn inference listings list, or run ornn help inference for command flags. Ornn CLI. To set price ceilings in the CLI, use --max-input-usd-per-million-tokens, --max-cached-input-usd-per-million-tokens, or --max-output-usd-per-million-tokens. In MCP, use inference_models_list and inference_listings_list to find an offer. Call inference_completions_create or inference_decisions_create with a body matching the REST request. Pass listing_id to pin an offer. MCP completions return one JSON response, so omit stream or set it to false. Connect the MCP server. For MCP price ceilings, pass max_input_usd_per_million_tokens, max_cached_input_usd_per_million_tokens, or max_output_usd_per_million_tokens as decimal strings alongside body. To look up one offer or provider through the CLI, use ornn inference listings show --listing-id ID or ornn inference providers list --ids IDS. MCP exposes the same reads as inference_listings_show and inference_providers_list.
Use ornn inference requests list for request history or add --summary usage --from TIME --to TIME for totals. Use ornn inference charges list to read receipts. All three reads accept a public model ID filter. MCP exposes the same reads in inference_requests_list and inference_charges_list.Pass the returned next_cursor as --after for request and listing pages or --cursor for charges. MCP inputs use API field names such as public_model_id and listing_id.

Credits and charges

Paid requests require a positive credit balance. An offer is free when its input and output rates are zero and its cached-input rate is zero or unset. Use Buy credits in Billing to add funds and Purchases to check payment status. Credits post after payment is confirmed. Inference and Compute share your saved card and credit balance. Ornn charges for reported input and output tokens at the prices saved when the request starts. Charges can appear after the request ends. Concurrent requests can consume more than the available balance before accounting finishes. Additional funding covers the amount owed before more paid requests can start. Click Stop in Chat or press Ctrl-C in the CLI to close your stream. If you disconnect over HTTP/1.1, generation can continue, and you may be charged for the full response. Reported usage can still be charged for a failed or cancelled request. A billable request needs reported input and output counts.
Charge receipts use the account and billing host, https://api.ornn.com. Read-only keys can list your organization’s receipts.
The response contains charges and next_cursor. A receipt includes the request ID, saved usage and rates, and the billed amount in customer_cents. Monetary amounts are exact decimal strings in cents. credit_applied_cents records the credits applied to that charge when it was recorded. A zero-cost receipt has customer_cents: "0" and ledger_transaction_id: null.Filter by exact public_model_id, model_listing_id, request_id, or provider_organization_id within your organization’s receipts. RFC 3339 from and to filter the recorded time, inclusive at the start and exclusive at the end. Results are newest recorded first. Use limit from 1 to 500, with a default of 500. Pass next_cursor as cursor with the same filters. An empty string marks the end.
If you get 402 insufficient_credits, add credits and try again. If you get 503 billing_unavailable, retry shortly.

Request history and usage

Usage shows requests, token volume, and cache hit rate by UTC date range, including requests for models since removed from the catalog. Load more reads older requests in the selected period. Use GET /v1/requests for the same organization-wide data, including Chat and calls from any of its keys. Read-only keys can use this endpoint. Replace the example dates with your window.
Filter either view by the saved public_model_id, model_listing_id, or both. Use request_id to look up the request on a receipt. RFC 3339 dates filter when requests started, inclusive at from and exclusive at to. History returns data newest first, with limit from 1 to 100 (default 50). Pass next_cursor as after with the same filters until the cursor is null. Totals require both dates within 90 days of each other. They return one by_model row per model and one days row per UTC day with requests, oldest first. Omit pagination parameters for totals.
A request records its saved model ID and rates, reported token counts, timestamps, and a status of running, completed, failed, or cancelled. Chat calls have api_key_id: null. Cancellation records a disconnect before completion or failure, with the time in cancelled_at.upstream_http_status records the HTTP status Ornn received from the provider. A stream can open with 200 and later fail or be cancelled. The field is null while the request is running, for older requests, or when Ornn receives no response headers.Input totals already include cached input. An unreported count is null on an individual request, and reported zero stays zero. The summary counts requests with input and output usage under requests_with_usage and requests with cached usage under requests_with_cached_usage. It includes reported counts for failed and cancelled calls. An empty period returns zero totals and an empty by_model.first_output_ms measures the time from upstream dispatch to the first streamed output. It is null when there was no streamed output. duration_ms ends when Ornn finishes reading, encounters an error, or closes on disconnect. Both measurements include network and queue time and can be null on older requests.The by-model summary reports median_first_output_ms and median_output_tokens_per_second for completed requests. Output rate uses output_tokens × 1000 / duration_ms, including the wait for first output. The sample counts are completed_requests_with_first_output and completed_requests_with_output_rate. Missing measurements and zero durations are excluded from the relevant median.

Serve models as a provider

Provider access scopes listings, requests, and earnings to your organization. The provider portal shows earnings and token counts by model for a UTC date range of up to 90 days. Provider earnings.
Use GET /v1/provider/listings to list your offers, or GET /v1/provider/listings/{listing_id} to inspect one. Create with POST /v1/provider/listings and update with PATCH /v1/provider/listings/{listing_id}. Writes require a read-write key.List catalog models with GET /v1/provider/models. Create a listing with its public_model_id, your upstream_url and upstream_model, and the api_type the endpoint serves. Set prices as decimal strings in the provider_*_usd_per_million_tokens fields. New listings start inactive. An optional upstream_credential is write-only.Test the upstream endpoint, then set active: true to publish. Set LISTING_ID to the offer UUID and use a provider read-write key. Check the public listing after publishing.
The public read returns 200 with the offer’s prices once the listing is active and has both input and output prices. The listing’s model_id stays the same across model renames.In the CLI, use ornn inference provider listings with list, show, create, or update. Pass --listing-id for show or update and --body JSON for writes. MCP exposes these actions as inference_provider_listings_* tools and accepts a body object for writes.
Use GET /v1/provider/requests to read requests served by your listings, including inactive listings. Read-only keys can use the same model and date filters, pagination, and summary=usage as customer request history.In Usage in the provider portal, choose a listing or search by request ID. Failure rate is failed requests divided by all requests. The CLI command is ornn inference provider requests list. In MCP, use inference_provider_requests_list.
Use GET /v1/ledger/inference-charges?view=provider on https://api.ornn.com with a provider organization key. The view accepts read-only keys and the same model, request, recorded-time, and pagination filters as charge receipts. The credential supplies the organization.Receipts include gross customer_cents, net provider_cents, fee_cents, saved usage and rates, and usage.transaction_fee_ppm. Amounts are exact decimal strings in cents.For totals, add summary=daily and RFC 3339 from and to within 90 days. The response groups the three amounts into UTC days and by_model. Model rows also show input, cached input, and output counts, ordered by net earnings. An empty range returns empty arrays. Omit limit and cursor for totals.In the CLI, run ornn inference charges list --view provider. Add --summary daily --from TIME --to TIME for daily totals.