# Numes documentation > Numes is an OpenAI-compatible marketplace API for AI inference from independent, verified providers. Base URL: https://api.numes.ai/api/v1 Every page is available as Markdown by appending `.md` to its URL. The OpenAPI contract is at https://0.0.0.0:3000/docs/openapi.json. ## Docs · Overview - [Quickstart](https://0.0.0.0:3000/docs/quickstart.md): Send your first request in a minute. Numes speaks the OpenAI Chat Completions API, so existing code needs only a new base URL and key. - [Principles](https://0.0.0.0:3000/docs/principles.md): The guarantees Numes makes about models, money, privacy and measurements, and where those guarantees stop. - [Models](https://0.0.0.0:3000/docs/models.md): How model IDs work, how to discover models and their provider endpoints, what the published statistics mean, and how listed prices relate to what you pay. - [FAQ](https://0.0.0.0:3000/docs/faq.md): Short answers to common questions about models, billing, privacy, keys and selling inference on Numes. ## Docs · Models & routing - [Provider routing](https://0.0.0.0:3000/docs/routing/provider-routing.md): How Numes chooses a provider endpoint for each request, and how the provider object lets you sort, pin, filter and cap prices. - [Fallbacks and reliability](https://0.0.0.0:3000/docs/routing/fallbacks.md): How Numes keeps failing endpoints out of routing, fails over between endpoints of a model before any output, and how to add model fallback. - [Verification and trust](https://0.0.0.0:3000/docs/routing/verification.md): What has to be true before a provider endpoint receives your requests, and what happens when it stops being true. ## Docs · Features - [Streaming](https://0.0.0.0:3000/docs/features/streaming.md): Stream chat output as Server-Sent Events, read the final usage chunk, cancel, handle mid-stream errors, and parse the wire format, including image and speech streams. - [Encrypted inference](https://0.0.0.0:3000/docs/inference/encrypted.md): Use end-to-end encrypted :e2ee models from Chat, coding agents or the Tinfoil SDK, and understand what each provider protects. - [Tool calling](https://0.0.0.0:3000/docs/features/tool-calling.md): Let models call functions that your code runs, and control which tools they call, how many and in what form. - [Hosted tools](https://0.0.0.0:3000/docs/features/hosted-tools.md): Use web search, fetching, code execution and other tools that run on the provider's side, with per-tool configuration and per-call billing. - [Structured outputs](https://0.0.0.0:3000/docs/features/structured-outputs.md): Get answers as a JSON object or as JSON that follows your schema with response_format, and validate the result. - [Reasoning](https://0.0.0.0:3000/docs/features/reasoning.md): Control how much a model thinks, read its reasoning, and carry reasoning state through multi-turn and tool conversations. - [Prompt caching](https://0.0.0.0:3000/docs/features/prompt-caching.md): Reuse repeated prompt prefixes through provider caches, read cache usage, and understand discount-only cache pricing. - [Sticky sessions](https://0.0.0.0:3000/docs/features/sessions.md): Keep the requests of one conversation on the same endpoint with session_id or X-Session-Id, so provider caches and reasoning state can be reused. ## Docs · Multimodal - [Multimodal](https://0.0.0.0:3000/docs/multimodal/overview.md): Send images, PDFs and audio to chat models, and generate images, speech, transcripts and embeddings through dedicated endpoints. - [Image inputs](https://0.0.0.0:3000/docs/multimodal/images.md): Send photos, screenshots and diagrams to vision-capable models with the image_url content part, by HTTPS URL or inline base64. - [PDFs and files](https://0.0.0.0:3000/docs/multimodal/pdfs.md): Attach PDF documents to chat requests with the file content part. PDFs go only to endpoints that read files natively. - [Audio inputs](https://0.0.0.0:3000/docs/multimodal/audio.md): Send recorded audio to audio-capable chat models with the input_audio content part. - [Image generation](https://0.0.0.0:3000/docs/multimodal/image-generation.md): Create images from a text prompt and optional reference images with POST /images, returned as base64 in one response or as a stream. - [Speech and transcription](https://0.0.0.0:3000/docs/multimodal/speech.md): Generate spoken audio from text with POST /audio/speech and transcribe recordings with POST /audio/transcriptions, using the OpenAI request shapes. - [Embeddings](https://0.0.0.0:3000/docs/multimodal/embeddings.md): Turn text, token arrays, images and PDFs into vectors with POST /embeddings for search, clustering, deduplication and retrieval. ## Docs · Accounts & billing - [API keys](https://0.0.0.0:3000/docs/account/api-keys.md): Create, limit, inspect, rotate and revoke the inference keys that authenticate model requests. - [Management keys](https://0.0.0.0:3000/docs/account/management-keys.md): Provision, limit, rotate and revoke inference keys from your own code with a management key. - [Credits and payments](https://0.0.0.0:3000/docs/account/credits.md): Read your balances, add USD by card, set up auto top-up and spending limits, and see how funds are held while requests run. - [Bitcoin payments](https://0.0.0.0:3000/docs/account/bitcoin.md): Fund a BTC balance over Lightning or on-chain, pay for requests in sats with BTC keys, and read USD-indexed Bitcoin prices. - [Usage accounting](https://0.0.0.0:3000/docs/account/usage-accounting.md): What you're charged for, what every usage field means, how cost is calculated, and how to look up the record of any request. - [Organizations](https://0.0.0.0:3000/docs/account/organizations.md): Share balances, keys, limits and provider resources with a team, with roles that decide who can spend, fund and administer. - [Support tickets](https://0.0.0.0:3000/docs/account/support.md): Submit a ticket, add details while you wait, and chat with the support agent who picks it up. - [Activity and logs](https://0.0.0.0:3000/docs/account/activity.md): Inspect individual requests in Logs, analyze spend and performance in Activity, attribute traffic to your apps, and use request IDs. ## Docs · Privacy & security - [Data retention and logging](https://0.0.0.0:3000/docs/privacy/data-retention.md): What the platform records about each request, what it never stores, how long records are kept, and what providers see. - [Provider data policies](https://0.0.0.0:3000/docs/privacy/provider-data-policies.md): What each provider endpoint declares about data collection, retention and location, where to read it, and how to route only to endpoints that meet your requirements. - [Account security](https://0.0.0.0:3000/docs/privacy/account-security.md): Sign-in methods, two-factor authentication, passkeys, sessions, and how to keep the identities and API keys on your account safe. - [Request policy](https://0.0.0.0:3000/docs/privacy/request-policy.md): Block phrases, replace text and add context in every request an account makes, restore replaced wording in responses, and review what the policy did. ## Docs · Integrations - [Integrations](https://0.0.0.0:3000/docs/integrations/overview.md): Use Numes from any OpenAI-compatible client by changing the base URL, the key and the model ID. - [OpenAI SDK](https://0.0.0.0:3000/docs/integrations/openai-sdk.md): Use the official OpenAI Python and TypeScript SDKs with Numes, including extension fields, exact costs, errors and retries. - [Coding agents](https://0.0.0.0:3000/docs/integrations/coding-agents.md): Start OpenCode, Pi and OMP on Numes with one command, or configure them by hand as an OpenAI-compatible provider. - [Raw HTTP](https://0.0.0.0:3000/docs/integrations/http.md): Call Numes without an SDK from curl, Python, Node.js or Go, with the headers, timeouts and retry rules a client needs. ## API reference · API guides - [API overview](https://0.0.0.0:3000/docs/api-reference/overview.md): Base URL, request format, endpoints, common headers and response basics for the Numes compatible API. - [Authentication](https://0.0.0.0:3000/docs/api-reference/authentication.md): Send an API key as a bearer token. Inference keys run requests, management keys administer inference keys, and each route accepts one kind. - [Parameters](https://0.0.0.0:3000/docs/api-reference/parameters.md): Every field of a chat completion request, with its type, range, default and effect on routing. - [Errors and debugging](https://0.0.0.0:3000/docs/api-reference/errors.md): The error envelope, every status code and error type, which errors to retry, and how to track down a failing request. - [Limits](https://0.0.0.0:3000/docs/api-reference/limits.md): Rate limits, body size, media and structure limits, time limits, and the balance and spending limits a request must fit. - [OpenRouter compatibility](https://0.0.0.0:3000/docs/api-reference/compatibility.md): What the Numes API shares with OpenRouter, every intentional difference, and a checklist for migrating an existing integration. ## Providers · Get started - [For providers](https://0.0.0.0:3000/docs/providers/overview.md): Sell inference on Numes from your own hardware or your upstream API accounts. How you connect, what the platform checks and how you're paid. - [Provider quickstart](https://0.0.0.0:3000/docs/providers/quickstart.md): Install the provider agent, sign in, set up an endpoint and keep it running. From zero to a live offer. - [Install and update](https://0.0.0.0:3000/docs/providers/install-and-update.md): Install the numes command, keep it updated automatically or by hand, roll back, uninstall and install offline. - [Hosted sources](https://0.0.0.0:3000/docs/providers/hosted.md): Sell inference from a cloud account without running a machine. The platform serves through your own upstream API key; you pay the upstream and customers pay you. ## Providers · Run a provider - [Inference sources](https://0.0.0.0:3000/docs/providers/sources.md): The sources the provider agent can serve, with their default addresses, authentication and setup requirements, catalog overlays and secret references. - [Profiles and configuration](https://0.0.0.0:3000/docs/providers/profiles.md): How the provider agent stores each endpoint as a profile, what the profile and configuration files contain, how secrets are referenced, and how to run several profiles. - [Pricing your models](https://0.0.0.0:3000/docs/providers/pricing.md): How provider prices work on Numes, from meters and currencies to reference prices, markups, price protection and price changes. - [Autopilot](https://0.0.0.0:3000/docs/providers/autopilot.md): Keep an endpoint's models and prices in line with its upstream at the upstream cost plus your markup, with a cost guard that holds underpriced models. - [Review and lifecycle](https://0.0.0.0:3000/docs/providers/lifecycle.md): What each provider, endpoint and model status means, how review and verification work, and how to pause, reconnect or delete supply. - [Measurements and quality](https://0.0.0.0:3000/docs/providers/measurements.md): What the platform measures about your endpoints, where you and customers see it, how capacity and task quality work, and how to earn more traffic. - [Earnings and payouts](https://0.0.0.0:3000/docs/providers/earnings.md): How provider earnings arise, when they become available, and how to withdraw USD to a bank account or BTC over Lightning and on-chain. ## Providers · Tools - [CLI reference](https://0.0.0.0:3000/docs/providers/cli.md): Every numes command, subcommand and flag for coding agents, sign-in, installation and serving inference as a provider. - [Terminal UI](https://0.0.0.0:3000/docs/providers/terminal-ui.md): The keyboard-first provider workspace built into the numes command: tabs, endpoint setup, keys, status pills and terminal size. - [Desktop app](https://0.0.0.0:3000/docs/providers/desktop.md): A graphical provider client for macOS and Linux that sets up and runs endpoints on this machine and on remote Linux machines over SSH. - [Provider security](https://0.0.0.0:3000/docs/providers/security.md): How the provider agent connects, which credentials it holds and how they're protected, what the platform sends you, and what your data declarations commit you to. ## API reference - [List models](https://0.0.0.0:3000/docs/api-reference/models/list-models.md): `GET /api/v1/models` — List models available to the authenticated account - [List model endpoints](https://0.0.0.0:3000/docs/api-reference/models/list-model-endpoints.md): `GET /api/v1/models/{author}/{slug}/endpoints` — List eligible provider endpoints for a model - [Create chat completion](https://0.0.0.0:3000/docs/api-reference/chat/create-chat-completion.md): `POST /api/v1/chat/completions` — Create a streaming or non-streaming chat completion - [Get generation](https://0.0.0.0:3000/docs/api-reference/chat/get-generation.md): `GET /api/v1/generation` — Get immutable request, usage, delivery, and cost metadata for a generation - [Resolve encrypted model](https://0.0.0.0:3000/docs/api-reference/encrypted-inference/resolve-encrypted-model.md): `POST /api/v1/e2ee/resolve` — Resolve an E2EE model before SDK encryption - [Create encrypted chat completion](https://0.0.0.0:3000/docs/api-reference/encrypted-inference/create-encrypted-chat-completion.md): `POST /api/v1/e2ee/chat/completions` — Relay an SDK-encrypted chat completion - [Create embedding](https://0.0.0.0:3000/docs/api-reference/embeddings/create-embedding.md): `POST /api/v1/embeddings` — Create text or multimodal embeddings - [Generate images](https://0.0.0.0:3000/docs/api-reference/media/create-image.md): `POST /api/v1/images` — Generate images - [Create speech](https://0.0.0.0:3000/docs/api-reference/media/create-speech.md): `POST /api/v1/audio/speech` — Generate speech audio - [Create transcription](https://0.0.0.0:3000/docs/api-reference/media/create-transcription.md): `POST /api/v1/audio/transcriptions` — Transcribe uploaded audio - [Get current key](https://0.0.0.0:3000/docs/api-reference/keys/get-current-key.md): `GET /api/v1/key` — Inspect the current API key - [List keys](https://0.0.0.0:3000/docs/api-reference/keys/list-keys.md): `GET /api/v1/keys` — List account API keys using a management key - [Create key](https://0.0.0.0:3000/docs/api-reference/keys/create-key.md): `POST /api/v1/keys` — Create an API key using a management key - [Get key](https://0.0.0.0:3000/docs/api-reference/keys/get-key.md): `GET /api/v1/keys/{hash}` — Get API key metadata using a management key - [Update key](https://0.0.0.0:3000/docs/api-reference/keys/update-key.md): `PATCH /api/v1/keys/{hash}` — Update an API key using a management key - [Delete key](https://0.0.0.0:3000/docs/api-reference/keys/delete-key.md): `DELETE /api/v1/keys/{hash}` — Delete an API key using a management key - [Get credits](https://0.0.0.0:3000/docs/api-reference/credits/get-credits.md): `GET /api/v1/credits` — Get net credits and settled usage in one settlement currency using a management key