Quickstart

Numes is a marketplace for AI inference. Independent providers serve the models; you call all of them through one OpenAI-compatible API and pay per request from a USD or Bitcoin balance. Every offer is reviewed and checked before it takes traffic, and you're charged only for output delivered to you.

Send your first request

1. 1

   Create an API key

   Sign in, open Keys and choose Create key. Pick the key's currency, USD or BTC. It can't be changed later, and every charge on the key is in that currency.

   The secret is shown once. Store it in an environment variable:

   Shell

   Copy Shell code

   export NUMES_API_KEY="sk-..."

2. 2

   Add credits

   Open Billing and add credits by card (USD) or with Bitcoin over Lightning or on-chain (BTC). Each request holds an upper bound of its cost before it runs, so your balance must cover that hold.

3. 3

   Call the API

   Send a chat completion to https://api.numes.ai/api/v1/chat/completions. Choose Try it to run the request from this page.

   cURLPythonTypeScriptJavaScriptGo

   Try itCopy cURL code

   curl -X POST "https://api.numes.ai/api/v1/chat/completions" \  -H "Authorization: Bearer $NUMES_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "model": "openai/gpt-6-luna",    "messages": [      {        "role": "user",        "content": "What is the meaning of life?"      }    ]  }'

The response follows the OpenAI shape and includes the exact cost in the key's currency:

{  "id": "0f5b5c9a-3a7e-4c6f-9d1e-2b8f7a6c5d4e",  "object": "chat.completion",  "created": 1790000000,  "model": "openai/gpt-6-luna",  "provider": "Example Provider",  "choices": [    {      "index": 0,      "finish_reason": "stop",      "message": { "role": "assistant", "content": "Forty-two, according to some." }    }  ],  "usage": {    "prompt_tokens": 14,    "completion_tokens": 8,    "total_tokens": 22,    "cost": 0.000006,    "cost_details": { "upstream_inference_cost": 0.000006 }  }}

usage.cost is what you were charged. The id is the generation ID: pass it to GET /generation for the full record of the request and its final cost.

Use the OpenAI SDK

Point the official SDK at Numes by changing the base URL and API key. Nothing else changes.

If the SDK isn't installed, run pip install openai in your Python environment or npm install openai in your TypeScript project. The cURL examples above don't need an SDK.

Run these examples locally or on your server; keep your API key out of browser code. See the OpenAI SDK guide for more examples.

import osfrom openai import OpenAI​client = OpenAI(    base_url="https://api.numes.ai/api/v1",    api_key=os.environ["NUMES_API_KEY"],)​completion = client.chat.completions.create(    model="openai/gpt-6-luna",    messages=[{"role": "user", "content": "What is the meaning of life?"}],)​print(completion.choices[0].message.content)

Stream tokens as they arrive

Set stream: true to receive Server-Sent Events. A successful stream ends with a chunk that carries usage, so you get the exact cost without a second request. See Streaming.

curl -N -X POST "https://api.numes.ai/api/v1/chat/completions" \  -H "Authorization: Bearer $NUMES_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "model": "openai/gpt-6-luna",    "stream": true,    "messages": [      {        "role": "user",        "content": "Write a haiku about routers."      }    ]  }'

Pick a model

Model IDs are author/model slugs, the same on every provider that serves the model. Browse the catalogue or list the models your key can use:

curl "https://api.numes.ai/api/v1/models" \  -H "Authorization: Bearer $NUMES_API_KEY"

Prices in the response are exact per-unit rates in your key's currency. For BTC keys, the unit of money is one satoshi.

Choose how requests are routed

When you set nothing, Numes picks among approved, healthy endpoints in a band close to the lowest price, and fails over to another endpoint before any output is delivered. Add a provider object to sort by throughput, latency or measured quality, cap prices per token, or restrict data handling:

{  "model": "openai/gpt-6-luna",  "messages": [{ "role": "user", "content": "Hello" }],  "provider": {    "sort": "throughput",    "data_collection": "deny",    "max_price": { "prompt": 0.000001, "completion": 0.000004 }  }}

Next steps