> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hopscotchlabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Completions and embeddings

> POST /v1/completions: the same key, the same model ids and the same balance as chat, with its one difference. Embeddings are not served yet.

The legacy text completion endpoint is served beside chat completions. It takes
the same key and the same `provider/model` ids, and draws on the same balance.
A request on it lands in Activity and on your statement exactly like a chat
request, filed under its own endpoint family so you can tell them apart.
The embeddings endpoint is not served yet; see [Embeddings](#embeddings).

Point your existing OpenAI client at `https://api.hopscotchlabs.ai` and give it a
Hopscotch API key. Nothing else about your code changes.

```text Base URL theme={"theme":{"light":"vitesse-light","dark":"vesper"}}
https://api.hopscotchlabs.ai
```

## Text completions

`POST /v1/completions` takes the OpenAI text completion body and returns the
OpenAI text completion object. `stream: true` is honoured and the stream is
OpenAI's.

```bash curl theme={"theme":{"light":"vitesse-light","dark":"vesper"}}
curl https://api.hopscotchlabs.ai/v1/completions \
  -H "Authorization: Bearer ub_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "prompt": "Write one sentence about rivers.",
    "max_tokens": 60
  }'
```

```python Python theme={"theme":{"light":"vitesse-light","dark":"vesper"}}
from openai import OpenAI

client = OpenAI(
    base_url="https://api.hopscotchlabs.ai/v1",
    api_key="ub_live_YOUR_KEY_HERE",
)

completion = client.completions.create(
    model="openai/gpt-4o-mini",
    prompt="Write one sentence about rivers.",
    max_tokens=60,
)
print(completion.choices[0].text)
```

```typescript Node theme={"theme":{"light":"vitesse-light","dark":"vesper"}}
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.hopscotchlabs.ai/v1",
  apiKey: "ub_live_YOUR_KEY_HERE",
});

const completion = await client.completions.create({
  model: "openai/gpt-4o-mini",
  prompt: "Write one sentence about rivers.",
  max_tokens: 60,
});
console.log(completion.choices[0].text);
```

The body is forwarded as you sent it, under the same rules as chat: two fields
are read to size what the request could cost, `model` and `max_tokens`, and
the handful of request fields we do not meter on our own provider credentials
are refused with a 400 that names the field in `param`. The list is the one on
[OpenAI compatibility](https://docs.hopscotchlabs.ai/get-started/openai-compatibility.md#request-parameters),
and it applies only when the request is served on our credentials: on your own
provider key the body is forwarded byte for byte.

The model must be one the catalog lists for the completions family. A model
that exists but is not offered on this endpoint is refused with HTTP 404 and
the code `model_not_available`, and the message says which families the
catalog does list it for. Ask [`GET /v1/models`](https://docs.hopscotchlabs.ai/features/models) for the
`endpoint_families` of a model before you rely on it here.

## Embeddings

Embeddings are not served yet, and we have no date to give. A call to
`POST /v1/embeddings` is refused with a 404 and the error type
`not_found_error`, and no vector comes back. The message says the model is not
currently available or is not offered on embeddings.

Until that changes, do not point an embeddings client at this API. If your
framework or tool reaches for an embeddings model by default, set its
embedding model to a provider you call directly. [`GET /v1/models`](https://docs.hopscotchlabs.ai/features/models)
shows what is callable today.

## Reading what a request cost

The completions endpoint adds no usage header to its reply. The token counts and the
charge are on the request's usage record, which you can read from the
dashboard or from the API with the request id every response carries. See
[Usage lookup](https://docs.hopscotchlabs.ai/features/usage-lookup.md).

## Next

> **[OpenAI compatibility](https://docs.hopscotchlabs.ai/get-started/openai-compatibility.md)**
>
> The full list of endpoints, the fields we refuse, and the headers we add.

> **[Models](https://docs.hopscotchlabs.ai/features/models.md)**
>
> How to find which endpoint families a model is offered on.

> [!NOTE]
>
> Every response carries the same id on two headers: `x-hopscotch-request-id`,
> which is ours, and `x-request-id`, which is the one the official OpenAI SDKs
> surface on their error objects. Every error envelope repeats it as
> `request_id`. Quote it when you ask us about a request. Without it we are
> guessing at which of your requests you mean.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.