---
title: "Create embedding (OpenAI-compatible)"
method: POST
path: "/v1/embeddings"
tags: ["Inference"]
---

# Create embedding (OpenAI-compatible)

`POST /v1/embeddings`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/embeddings`
- Auth: HTTP bearer

OpenAI-compatible embeddings endpoint backed by EmbeddingGemma-300M
on the Apple Neural Engine. Default model `embeddinggemma` (base,
seqLen=512); `embeddinggemma-tools` (LoRA, seqLen=512) selectable
via `model`. `seqLen` is read from the active R2 bundle's compiled
`input_ids` shape, not hardcoded. Inputs exceeding it are rejected with
`context_length_exceeded`. Supports Matryoshka truncation via
`dimensions` (768/512/256/128) with automatic re-L2-normalization,
and `encoding_format: "base64"` for little-endian float32 packing.

## Request body

- object
  - `input` union, required
    - string
    - string[]
  - `model` string: Must start with `embeddinggemma`.
  - `task` 'retrieval.query' | 'retrieval.document' | 'classification' | 'clustering' | 'sts'
  - `encoding_format` 'float' | 'base64'
  - `dimensions` 768 | 512 | 256 | 128
  - `user` string: Accepted and ignored, matches OpenAI client expectations.

## Response `200`

Embedding response

- object
  - `object` 'list', required
  - `data` object[], required
    - `object` 'embedding'
    - `index` integer
    - `embedding` union
      - number[]
      - string: base64-encoded little-endian float32 buffer
  - `model` string, required
  - `usage` object: Omitted entirely when no exact token count exists. The count is the one the producer itself charged, never an estimate: llama-server reports it in its own `usage` block, and the in-process ANE tokenizer measures it exactly. When neither is available the object is absent rather than fabricated or zeroed, which is why it is not in `required`. An absent field is how "we do not know" is spelled in JSON.
    - `prompt_tokens` integer
    - `total_tokens` integer

## Other responses

- `400`: Invalid request or context_length_exceeded
- `503`: Model not loaded

---

[API](https://skmtc.dev/modelpiper/apis/toolpiper-api.md) · [All operations](https://skmtc.dev/modelpiper/apis/toolpiper-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelpiper/apis/toolpiper-api/revisions/6722bf56385c?raw)