API & Error Codes
Embeddings and retrieval
How to use the Xisu AI /v1/embeddings endpoint: embedding models only, the four input shapes from strings to integer token arrays, the difference between the item limit and the total token limit, and three ways it differs from chat.
POST /v1/embeddings turns text into vectors for retrieval, clustering and RAG. The protocol matches OpenAI's and fields pass through untouched.
The model must be an embedding model
Pick model from the entries marked as embedding models on the Models & pricing page. Sending a chat model here returns 400 model_not_supported_for_endpoint, and the message says which kind it actually is — caught before forwarding, so it doesn't burn an upstream call.
To filter programmatically, GET /v1/models accepts a non-standard parameter: ?modality=embedding.
The four shapes of input
| Shape | Example | How tokens are counted |
|---|---|---|
| String | "hello" |
Estimated from characters |
| Array of strings | ["a", "b"] |
Estimated from characters |
| Array of integers | [15339, 1917] |
Already tokens — the length is exact |
| Array of integer arrays | [[15339], [1917]] |
Sum of the lengths |
For the first two we estimate the token count; for the last two you have already tokenized, so the length is the real number.
⚠️ Two limits, and they measure different things
| Limit | Value | Applies to |
|---|---|---|
| Item count | 2048 | Array of strings / array of integer arrays |
| Total tokens | 2,000,000 | Array of integers / array of integer arrays |
They're separate for a practical reason: a flat [15339, 1917, ...] is one input whose length is a token count, not an item count. Applying the item limit to it would reject a perfectly legal 500,000-token request as if it were "500,000 items".
Exceeding either returns 400 invalid_request with both the actual value and the limit in the message. An empty input, or a shape we don't recognise, returns the same code.
Three ways it differs from chat
- No streaming — a vector is returned complete, in one response. There is no SSE.
- There is a hard timeout — if the whole operation exceeds it you get a
504. Nothing was produced, and you are not charged. - The bigger the batch, the more the timeout matters — 2048 is a ceiling, not a recommendation. Upstream processing time doesn't scale linearly with batch size; several smaller batches are often both faster and steadier.
The response shape matches OpenAI:
{ "object": "list",
"data": [{ "embedding": [0.1, ...], "index": 0 }],
"usage": { "prompt_tokens": 8, "total_tokens": 8 } }
Billing
The same machinery as chat: per token, deducted from the balance in real time, failures not billed. Embeddings have input only and no output, so only the input side is charged.