# Docs

> The Markdown form of https://openfill.ai/docs. The index of every docs page is https://openfill.ai/llms.txt, and every page in one file is https://openfill.ai/llms-full.txt.

OpenFill is an OpenAI-compatible inference API priced by a live clearing market. Point your SDK at the base URL, name a price limit, and pay the level your request executes at.

## Quickstart

1. Sign up and verify your email. Every account opens with $1 of credit, and no card is needed. Beyond that, credits are prepaid on [Credits](https://openfill.ai/billing), and a request runs only when your balance covers it at the level of the moment, or at the prices of a fixed-price model.
2. Make a key on [API keys](https://openfill.ai/keys) and put it in `OPENFILL_API_KEY`.
3. Send a request with a price limit. The base URL is `https://api.openfill.ai/v1` and the key goes in the `Authorization` header as a bearer token, as with OpenAI.
4. Read the receipt. Every completion carries `usage.x_market`: what it was charged at, the price it rested at, and what it cost. On a stream, send `stream_options: {"include_usage": true}` and it arrives in a final chunk.

Set `OPENFILL_API_KEY` to a key from [API keys](https://openfill.ai/keys) before running an example. A key starts with `of_live_` and is shown once.

> `market-preview` is a preview of the market, which opens soon: its prices are simulated until then, a request to it answers `400 model_preview` with nothing charged, and the call below runs today with the id of a [fixed-price model](https://openfill.ai/docs/models#fixed-price).

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url=(
        "https://api.openfill.ai/v1"
    ),
    api_key=os.environ[
        "OPENFILL_API_KEY"
    ],
)

r = client.chat.completions.create(
    model="market-preview",
    messages=[
        {"role": "user", "content": "hi"}
    ],
    extra_body={"price_limit": 0.10},
)
print(r.choices[0].message.content)
print(r.usage)
```

```typescript
import OpenAI from "openai";

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

const r = await client.chat.completions.create(
  {
    model: "market-preview",
    messages: [{ role: "user", content: "hi" }],
  },
  { headers: { "X-Price-Limit": "0.10" } },
);
console.log(r.choices[0].message.content);
console.log(r.usage);
```

**curl**

```bash
curl "https://api.openfill.ai/v1/chat/completions" \
  -H "Authorization: Bearer $OPENFILL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "market-preview",
    "messages": [
      {"role": "user", "content": "hi"}
    ],
    "price_limit": 0.10
  }'
```

**Response**

```json
# usage.x_market, on every completion
{
  "order_id": "<order_id>",
  "pricing": "market",
  "level_at_execution": 0.0143,
  "bid": 0.1,
  "charged_usd": 0.0000174
}
```

> The price limit is in USD per 1M input tokens at the reference mix (90% cached, 2% output). The first of these that is set wins: `price_limit` on the request, the `X-Price-Limit` header, the key's price limit for that model, then your account default for that model. Defaults are set per model. A request to a market model with none of them is refused with `400 missing_price_limit`.

## The one idea

Each market model has one clearing level: the price, in USD per 1M input tokens at the reference mix, that the market is clearing at right now. It moves with real load. With spare capacity it moves toward 0, and execution is free when it reaches 0.

Every request to a market model names a price limit: a ceiling on what you pay, and your rank in the book. On every tick the market admits from the top of the book while the pods have room, so a request at or above the level normally runs at once, and one below it waits while capacity is short and runs when there is room, until your timeout, or until you cancel. Whenever it runs you are charged the level at that moment, up to your price limit.

Nothing that did not run is charged: a request that times out in the queue, is cancelled while queued, or fails before producing output costs nothing, and a price-locked request that misses its window costs nothing. A request that is already executing when you cancel or disconnect runs to completion and is charged.

Some models are sold at a fixed price instead, charged at three published prices per 1M tokens; [the models page](https://openfill.ai/docs/models#fixed-price) lists them.

## Choose how a request runs

| Mode | How | What happens | Read |
| --- | --- | --- | --- |
| Wait in the book | price_limit | The default. The request rests at your price limit and runs when the market admits it, paying the level or your price limit, whichever is lower. | [Orders](https://openfill.ai/docs/orders) |
| Lock the price | price_lock: true | The request bids the published quote, or your price limit if that is lower, so the most it can cost is known before you send. It starts inside a short window or expires with 429. | [Price lock](https://openfill.ai/docs/price-lock) |
| Detach | detached: true | 202 and an order id at once. The order waits on your behalf and you collect the result from its result URL, once data storage is on for your account. | [Detached orders](https://openfill.ai/docs/detached) |
| Batch | POST /v1/batches | Thousands of requests in a JSONL file, each line at the batch's price limit or its own, results in a file. | [Batch API](https://openfill.ai/docs/batch) |

## Common errors

| Status | Type or code | Meaning | What to do |
| --- | --- | --- | --- |
| 400 | code missing_price_limit | No price limit stated on the request, the header, the key or the account. | Send price_limit, or set a default on Bidding. |
| 400 | code model_preview | The model is a preview of the market, which opens soon. Nothing was charged. | Send the request to a fixed-price model, listed at GET /v1/models. |
| 402 | code insufficient_balance | Your balance does not cover this request at the current level, or at a fixed-price model's prices. A level of 0 needs no balance. | Add credits, or wait for the level to fall on a market model. |
| 429 | code capacity_unavailable | A price-locked request did not start inside its execute window, or a request to a fixed-price model did not start before its timeout. Nothing was charged. | Retry. Send a locked request without the lock so it waits. Give a fixed-price request a longer max_wait, or add credits if your balance cannot cover it at the model's prices. |
| 429 | type rate_limit_error | A per-key or per-account ceiling was hit. | Wait for Retry-After. The SDKs do this. |
| 408 | type order_expired | A request to a market model waited out its timeout, yours or the account's, without starting. Nothing was charged. | Raise the price limit or the timeout, or retry. |

Every status the API can return, and which ones to retry, is on [errors and retries](https://openfill.ai/docs/errors).

## Where to next

| Page | What it answers |
| --- | --- |
| [How pricing works](https://openfill.ai/docs/pricing) | What the level is, what you pay, and a worked clearing with numbers. |
| [Integrations](https://openfill.ai/docs/integrations) | Pointing a framework, a coding agent or a gateway at OpenFill. |
| [OpenAI compatibility](https://openfill.ai/docs/compatibility) | What of the OpenAI API is served, passed through, or refused. |
| [API reference](https://openfill.ai/docs/api) | Every endpoint, parameter and header. |

Next: [OpenAI compatibility](https://openfill.ai/docs/compatibility).