API reference

fremai exposes an OpenAI-compatible REST API. The request and response shapes mirror the OpenAI API for the routes below, so any OpenAI SDK, curl, or tool works by changing only the base URL and key.

Base URL: https://api.fremai.eu/v1
Auth: Authorization: Bearer sk-fremai-… (see authentication)
Machine-readable spec: /api/openapi.yaml (OpenAPI 3.1)

/v1 is a compatibility marker, not a version axis. Advertise and use https://api.fremai.eu/v1; the ingress also accepts the bare-root form for clients configured without /v1.

OpenAPI specification

The full machine-readable contract is published at docs.fremai.eu/api/openapi.yaml. Load it into your OpenAPI tooling (client generators, Postman/Insomnia, Swagger/Redoc viewers) to explore every schema and generate a typed client.

Endpoints

`POST /chat/completions`

Create a chat completion — the primary surface. Send a model id and a messages array; receive a chat.completion object. Set stream: true for a Server-Sent Events stream of chat.completion.chunk objects terminated by data: [DONE].

Common request fields: model (required), messages (required), temperature, top_p, max_tokens, stream, stop.

curl https://api.fremai.eu/v1/chat/completions \
  -H "Authorization: Bearer $FREMAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"glm-5.2","messages":[{"role":"user","content":"Hello"}]}'

`POST /completions`

Legacy text completions. Send a model and a prompt (string or array); receive a text_completion object. Prefer /chat/completions for new work.

`POST /embeddings`

Create embedding vectors. Send a model and input (string or array of strings); receive a list of embedding vectors plus token usage. Use a model id from GET /models.

`GET /models`

List the curated fremai catalog available to your key. Each entry’s id is the value you pass as model. See the model catalog.

Usage and billing

Every response includes a usage object with prompt_tokens, completion_tokens, and total_tokens. These backend-reported counts are the basis for metering and billing — the same numbers your prepaid credit is debited against. See rate limits & budgets.

Errors

Errors use the OpenAI-compatible envelope:

{
  "error": {
    "message": "…",
    "type": "…",
    "param": null,
    "code": null
  }
}

The full status-code list (400, 401, 402, 404, 429) is in the error reference.