# Quickstart

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

Source: https://0.0.0.0:3000/docs/quickstart
Documentation index: https://0.0.0.0:3000/docs/llms.txt

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.

| Approach | Best for |
| --- | --- |
| [HTTP API](#send-your-first-request) | Any language, full control over every field |
| [OpenAI SDK](#use-the-openai-sdk) | Existing OpenAI code in Python and TypeScript |
| [Coding agents](/docs/integrations/coding-agents) | OpenCode, Pi and OMP, started with `numes run opencode` |

## Send your first request

:::steps
### Create an API key

Sign in, open [Keys](/dashboard/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:

```bash
export NUMES_API_KEY="sk-..."
```

### Add credits

Open [Billing](/dashboard/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.

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

```request
{
  "method": "POST",
  "path": "/chat/completions",
  "body": {
    "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:

```json title="Response"
{
  "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`](/docs/api-reference/chat/get-generation) for the full record of the request and its final cost.

:::tip Every response carries a request ID
Each response includes an `X-Request-Id` header. Quote it when you contact support; never share your key or prompt.
:::

## 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](/docs/integrations/openai-sdk) for more examples.

:::code-group
```python title="Python"
import os
from 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)
```

```typescript title="TypeScript"
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.numes.ai/api/v1",
  apiKey: process.env.NUMES_API_KEY,
});

const completion = await client.chat.completions.create({
  model: "openai/gpt-6-luna",
  messages: [{ role: "user", content: "What is the meaning of life?" }],
});

console.log(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](/docs/features/streaming).

```request
{
  "method": "POST",
  "path": "/chat/completions",
  "body": {
    "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](/models) or list the models your key can use:

```request
{
  "method": "GET",
  "path": "/models"
}
```

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:

```json
{
  "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

:::cards
- {network} [Provider routing](/docs/routing/provider-routing) Control order, sorting, fallbacks and price ceilings.
- {waves} [Streaming](/docs/features/streaming) Event format, final usage chunk and cancellation.
- {wrench} [Tool calling](/docs/features/tool-calling) Let models call your functions.
- {coins} [Credits and payments](/docs/account/credits) Card and Bitcoin funding, auto top-up and limits.
- {code} [API reference](/docs/api-reference/overview) Every endpoint, field and error, with a live playground.
- {server} [Become a provider](/docs/providers/overview) Sell inference from your own hardware or accounts.
:::