> For the complete documentation index, see [llms.txt](https://docs.tensorx.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tensorx.ai/api-reference/embeddings.md).

# Embeddings

TensorX serves text embeddings through the standard OpenAI-compatible `/v1/embeddings` endpoint. One embedding model is available:

| Model                     | Output dimensions                             | Max input     | Pricing                                            |
| ------------------------- | --------------------------------------------- | ------------- | -------------------------------------------------- |
| `qwen/qwen3-embedding-8b` | 4096 by default, 32 to 4096 with `dimensions` | 40,960 tokens | See [tensorx.ai/models](https://tensorx.ai/models) |

## Basic usage

```python
from openai import OpenAI

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

resp = client.embeddings.create(
    model="qwen/qwen3-embedding-8b",
    input="The capital of France is Paris."
)

vector = resp.data[0].embedding   # list of 4096 floats
```

Batch inputs by passing a list. Each item gets its own vector, returned in the same order:

```python
resp = client.embeddings.create(
    model="qwen/qwen3-embedding-8b",
    input=["first document", "second document", "third document"]
)
vectors = [d.embedding for d in resp.data]
```

## Parameters

| Parameter         | Type                       | Required | Description                                                                                                    |
| ----------------- | -------------------------- | -------- | -------------------------------------------------------------------------------------------------------------- |
| `model`           | string                     | Yes      | Model ID: `qwen/qwen3-embedding-8b`                                                                            |
| `input`           | string or array of strings | Yes      | Text to embed. Every item must be non-empty.                                                                   |
| `dimensions`      | integer                    | No       | Length of each output vector, from 32 to 4096. Omit it for the full 4096.                                      |
| `encoding_format` | string                     | No       | Accepted for compatibility. Vectors are always returned as float arrays, including when `base64` is requested. |

## Shorter vectors with `dimensions`

Qwen3-Embedding is trained with Matryoshka Representation Learning, so the first N values of the vector are a usable embedding on their own. Pass `dimensions` to have the API return that shorter vector. The API truncates the full vector to the length you ask for and then L2-normalises it, so the result is ready to use for cosine similarity.

```python
resp = client.embeddings.create(
    model="qwen/qwen3-embedding-8b",
    input="The capital of France is Paris.",
    dimensions=256
)

vector = resp.data[0].embedding   # list of 256 floats, unit length
```

Any value from 32 to 4096 works. The model card recommends 32 as the smallest useful size. Smaller vectors cost less to store and compare. Larger vectors keep more detail. For most retrieval workloads, 256 to 1024 is a good place to start. Measure recall against the full 4096 on your own data before you commit to a size.

Use the same `dimensions` value for every vector in an index. A query embedded at one size cannot be compared with documents embedded at another.

{% hint style="info" %}
If you already have full 4096-dimensional vectors stored, you can shorten them yourself instead of re-embedding: keep the first N values and re-normalise. This gives the same result as requesting `dimensions=N`.

```python
import numpy as np

full = np.array(resp.data[0].embedding)   # 4096 dims
short = full[:256]                        # keep the first 256
short = short / np.linalg.norm(short)     # re-normalise
```

{% endhint %}

## Input limit

The model context length is **40,960 tokens**. Requests above this are rejected; nothing is truncated for you.

For RAG or document indexing, chunk your text to well under 40,960 tokens per item before sending. Chunks of 512 to 1,024 tokens are typical for retrieval.

{% hint style="warning" %}
Every item in a batch must be non-empty. A blank or whitespace-only string fails the whole request. Filter empty strings before sending.
{% endhint %}

## Errors

A `dimensions` value outside the supported range and a blank input item both return the same generic response:

```
HTTP 400
{ "error": { "message": "The request contained an invalid argument.
  Please check your request parameters and try again.",
  "type": "invalid_request_error", "code": "400" } }
```

The API does not tell you which of these caused it, so check them in order:

| Cause                                     | What to change                          |
| ----------------------------------------- | --------------------------------------- |
| `dimensions` is 0, negative or above 4096 | Use a value from 32 to 4096, or omit it |
| Blank or whitespace-only item in a batch  | Filter empty inputs before sending      |

An input over 40,960 tokens also returns HTTP 400, with a short message that names only the model:

```
HTTP 400
{ "error": { "message": "model=qwen/qwen3-embedding-8b.",
  "type": "invalid_request_error", "code": "400" } }
```

One item over the limit fails the whole batch. Chunk the input to smaller pieces and resend.

The embedding model serves the embeddings endpoint only. A chat completion or completion request that names `qwen/qwen3-embedding-8b` is rejected with its own message:

```
HTTP 400
{ "error": { "message": "This model only supports the embeddings endpoint.",
  "type": "invalid_request_error", "code": "400" } }
```

If a tool sends that request, it has the embedding model configured as a chat model. Point its chat setting at a chat model from [`/v1/models`](/api-reference/models.md) and keep `qwen/qwen3-embedding-8b` for embeddings.

## See Also

* [Models](/api-reference/models.md) - full model catalogue
* [Rate Limits](/api-reference/rate-limits.md)
* [API Examples](/api-reference/api-examples.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.tensorx.ai/api-reference/embeddings.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.