# API overview

The exchange has one public API. An OpenAI client, an Anthropic client or plain HTTP can call it. Each endpoint page of this reference comes from the OpenAPI document of the exchange, so it always agrees with the exchange.

## Send a request

Send an API key and a `model`. The exchange auctions the request, sets a price cap and charges for the tokens used. The price cap is the most that the job can cost.

```bash
curl https://router.inference.ai.exchange/v1/chat/completions \
  -H "Authorization: Bearer $LIQUID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "liquid.auto", "messages": [{"role": "user", "content": "Hello"}]}'
```

The response has the usual fields of the format, and one more: the `exchange` block. See [What each job returns](#what-each-job-returns). The [Quickstart](https://inference.ai.exchange/docs/quickstart.md) shows how to get a key.

## Endpoints

### Buy inference

| Endpoint                      | Page                              | Description                                                   |
| ----------------------------- | --------------------------------- | ------------------------------------------------------------- |
| `POST /v1/chat/completions`   | [Chat Completions](https://inference.ai.exchange/docs/api-chat.md) | OpenAI Chat Completions.                                      |
| `POST /v1/responses`          | [Responses](https://inference.ai.exchange/docs/api-responses.md)   | OpenAI Responses, without stored state.                       |
| `POST /v1/messages`           | [Messages](https://inference.ai.exchange/docs/api-messages.md)     | Anthropic Messages, and a token count estimate.               |
| `POST /v1/systemone`          | [Decisions](https://inference.ai.exchange/docs/api-systemone.md)   | Typed questions, with a probability for each option. In beta. |
| `POST /v1/embeddings`         | [Embeddings](https://inference.ai.exchange/docs/api-embeddings.md) | Vectors for text.                                             |
| `POST /v1/images/generations` | [Images](https://inference.ai.exchange/docs/api-images.md)         | Generated images.                                             |
| `POST /v1/audio/speech`       | [Speech](https://inference.ai.exchange/docs/api-speech.md)         | Spoken audio.                                                 |
| `POST /v1/videos`             | [Video](https://inference.ai.exchange/docs/api-videos.md)          | Generated video, with a status and a download.                |
| `GET /v1/models`              | [Models](https://inference.ai.exchange/docs/api-models.md)         | The names that you can use as `model` now.                    |

### Read the market

The [Market data](https://inference.ai.exchange/docs/api-market.md) page lists the public book, depth, routers and the live feed. These endpoints need no key.

### Sell inference

The [Provider API](https://inference.ai.exchange/docs/api-provider.md) page lists the catalogue calls and the session. Provider credentials are different from API keys. See [Provider credentials](https://inference.ai.exchange/docs/provider.md).

If you already have a client, read [What changed in the API](https://inference.ai.exchange/docs/api-changes.md).

## Field order

The tables and the examples of this documentation list the fields of a request in one order:

1. `model`.
2. The content: `messages`, `prompt`, `input` or `file`.
3. The references: `input_references`.
4. The shape of the output: for example `n`, `size`, `voice`, `response_format`, `output_format`.
5. The controls: for example `temperature`, `top_p`, `seed`, `stop`, `quality`.
6. The delivery: `stream`, `callback_url`.
7. `exchange`, always last.

The order is for the reader. The exchange reads a JSON body in any order.

## Authentication

Send an API key in one of two headers. Both headers work on every endpoint.

| Header                              | Used by              |
| ----------------------------------- | -------------------- |
| `Authorization: Bearer sk-liquid-…` | OpenAI clients, curl |
| `x-api-key: sk-liquid-…`            | Anthropic clients    |

The scope of the key decides what it can do. A `spend` key can place jobs. A `read` key can read receipts and the balance. See [API keys](https://inference.ai.exchange/docs/keys.md).

## What each job returns

Each job response has the shape of the format that you used, with one more field: the `exchange` block. It names the job, the provider handle, the price cap and the charge.

Two headers arrive before the first token:

| Header             | Meaning                                                        |
| ------------------ | -------------------------------------------------------------- |
| `x-liquid-job-id`  | The job id. Use it to read the receipt.                        |
| `x-liquid-cap-usd` | The maximum charge for this job, set before the output starts. |

To read the block again later, call `GET /v1/jobs/{job_id}`. It returns only the block. `GET /v1/exchange/jobs/{job_id}` returns the whole receipt, with the charge breakdown. See the [Quickstart](https://inference.ai.exchange/docs/quickstart.md).

To see how the exchange chose the offer, send the `x-liquid-explain: true` request header. The block then has a `routing` object.

To choose the models, the strategy or the limits, send an `exchange` block in the request body, or `x-liquid-*` headers. See [Purchasing rules](https://inference.ai.exchange/docs/rules.md). For failures, see [Errors](https://inference.ai.exchange/docs/errors.md).

## Reference

### Base URLs

| Format    | Base URL                                  |
| --------- | ----------------------------------------- |
| OpenAI    | `https://router.inference.ai.exchange/v1` |
| Anthropic | `https://router.inference.ai.exchange`    |

An Anthropic client adds `/v1/messages` to its base URL. An OpenAI client adds only the endpoint name.

### The OpenAPI document

The document is at `/v1/openapi.json` on the exchange. It needs no credential. You can load it into a client generator, Postman, Insomnia or Bruno. It lists only the public API.