# Embeddings

`POST https://api.llm.buzz/api/v1/embeddings`

OpenAI's Embeddings API, for embeddings models: vectors for one or more inputs, never streamed. A call bills the input tokens the provider reports at that provider's input price, with no output. A request without `dimensions` gets vectors of the model's declared dimensions. Send no `stream`, or `false`; unknown fields are dropped. There is no answer store: `Idempotency-Key` is ignored, so a retry is a new, billed call. `GET /api/v1/embeddings/models` lists the embeddings models your key can call.

Authentication: an inference key, as `Authorization: Bearer KEY`.

## Body

- `model` (string, required): An embeddings model from `GET /api/v1/embeddings/models`, such as `qwen/qwen3-embedding-8b`.
- `input` (string or string[] or integer[] or integer[][], required): A string, a list of strings, a list of token IDs, or a list of such lists. Token IDs must match the model's tokenizer.
- `encoding_format` (string, one of `float`, `base64`): How the vectors come back.
- `dimensions` (integer): The vectors' size, sent to the provider as given.
- `provider` (object): Steers one request across the model's providers. With the OpenAI SDK, send it in `extra_body`. Every field accepts `null`. A name matches a provider's display name, its tag or the tag's first part, ignoring case: `llm.buzz` or `llm-buzz` names llm.buzz's own provider, and `llm-buzz/eu` only its capacity in the EU.
  - `order` (string[]): Try these providers first, in this order, then the others. At most 64 names.
  - `only` (string[]): Use only these providers.
  - `ignore` (string[]): Never use these providers.
  - `allow_fallbacks` (boolean): `false` stops moving to other providers.
  - `sort` (string, one of `price`, `throughput`, `latency`, `smart`): The order to try providers in. Ignored when `order` is set.
  - `zdr` (boolean): `true` keeps the request on providers that declare 0 days of retention.
  - `data_collection` (string, one of `allow`, `deny`): `deny` keeps the request on providers that declare no training and 0 days of retention.
- `user` (string): Your end user's label, recorded and never forwarded.

## Responses

- 200: One vector per input, exactly as the provider returned it, with `provider` and `usage`, whose `cost` is in US dollars.
- 400: A field is missing or malformed (`invalid_request`, with `metadata.param`), or the model cannot do what the request asks (`unsupported_capability`).
- 401: No key, or the key is unknown, expired, revoked or disabled.
- 402: Your balance is spent and the model is not free, or the request could cost more than your balance.
- 404: No model has this name, or your key may not call it.
- 429: Providers are throttling, or the model is at capacity (`unavailable_route`): retry after `Retry-After` seconds. Or a free offer's allowance is used (`free_allowance_exceeded`): your organization's tokens, or your key's requests per minute. Choose a paid model, or for the per-minute limit retry after `Retry-After` seconds.

## Example (curl)

```bash
curl -X POST https://api.llm.buzz/api/v1/embeddings \
  -H "Authorization: Bearer $LLM_BUZZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "qwen/qwen3-embedding-8b",
  "input": "The quick brown fox"
}'
```

## Example response

```json
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        0.0123,
        -0.0456
      ]
    }
  ],
  "model": "qwen/qwen3-embedding-8b",
  "provider": "DeepInfra",
  "usage": {
    "prompt_tokens": 4,
    "total_tokens": 4,
    "cost": 4e-8
  }
}
```