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

# Embeddings

> Create dense vector embeddings with the Mesh API and the official SDKs.

The Embeddings API turns text into vectors you can use for semantic search, retrieval, clustering, and ranking.

```http theme={null}
POST https://api.meshapi.ai/v1/embeddings
Authorization: Bearer rsk_<your_key>
```

## Quick start

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl https://api.meshapi.ai/v1/embeddings \
      -H "Authorization: Bearer <YOUR_RSK_KEY>" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "openai/text-embedding-3-small",
        "input": "The quick brown fox jumps over the lazy dog."
      }'
    ```
  </Tab>

  <Tab title="Node.js SDK">
    ```ts theme={null}
    import { MeshAPI } from "meshapi-node-sdk";

    const client = new MeshAPI({
      baseUrl: "https://api.meshapi.ai",
      token: process.env.MESH_API_KEY!,
    });

    const response = await client.embeddings.create({
      model: "openai/text-embedding-3-small",
      input: "The quick brown fox jumps over the lazy dog.",
    });

    console.log(response.data[0]?.embedding);
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python theme={null}
    from meshapi import EmbeddingsParams, MeshAPI

    client = MeshAPI(
        base_url="https://api.meshapi.ai",
        token="rsk_...",
    )

    response = client.embeddings.create(
        EmbeddingsParams(
            model="openai/text-embedding-3-small",
            input="The quick brown fox jumps over the lazy dog.",
        )
    )

    print(response.data[0].embedding)
    ```
  </Tab>
</Tabs>

## Request fields

| Field              | Type                                       | Notes                                                                    |
| ------------------ | ------------------------------------------ | ------------------------------------------------------------------------ |
| `model`            | string                                     | Embedding model ID. Required unless your key has a default model.        |
| `input`            | string \| string\[] \| int\[] \| int\[]\[] | Text or tokenized input.                                                 |
| `dimensions`       | integer                                    | Optional output size for models that support truncation.                 |
| `encoding_format`  | `"float"` \| `"base64"`                    | Output format.                                                           |
| `input_type`       | string                                     | Optional hint for asymmetric embedding models.                           |
| `provider`         | string \| object                           | Optional provider routing preferences.                                   |
| `instructions`     | string                                     | Optional task instructions for models that support them (e.g. BytePlus). |
| `sparse_embedding` | boolean                                    | Optional — request a sparse embedding (BytePlus).                        |
| `user`             | string                                     | Optional end-user identifier for abuse monitoring (max 256 characters).  |

## Batch input in a single request

You can embed multiple strings in one API call:

```bash theme={null}
curl https://api.meshapi.ai/v1/embeddings \
  -H "Authorization: Bearer <YOUR_RSK_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/text-embedding-3-small",
    "input": [
      "first sentence",
      "second sentence",
      "third sentence"
    ]
  }'
```

The returned `data` array matches the order of your input array.

## Response shape

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [-0.0123, 0.0456]
    }
  ],
  "model": "openai/text-embedding-3-small",
  "usage": {
    "prompt_tokens": 12,
    "total_tokens": 12
  }
}
```

## Choosing a model

Use `GET /v1/models` to inspect available embedding models and their pricing. For embeddings, the most useful fields are:

* `model_type`
* `context_length`
* `pricing`
* `is_free`

## SDK coverage

The official SDKs all expose first-class embeddings resources:

* Node: `client.embeddings.create(...)`
* Python: `client.embeddings.create(...)`
* Go: `client.Embeddings.Create(...)`
* Java: `client.embeddings().create(...)`

## Common errors

| HTTP  | Meaning                      |
| ----- | ---------------------------- |
| `401` | Missing or invalid API key   |
| `402` | Balance or spend limit issue |
| `422` | Invalid request body         |
| `429` | Rate limit exceeded          |

***

## Available models

| Model                                  | Dimensions | Best for                     |
| -------------------------------------- | ---------- | ---------------------------- |
| `bedrock/amazon.titan-embed-text-v2:0` | 1024       | General-purpose English text |
| `openai/text-embedding-3-small`        | 1536       | Fast, cost-efficient         |
| `openai/text-embedding-3-large`        | 3072       | Highest accuracy             |
| `openai/text-embedding-ada-002`        | 1536       | Legacy OpenAI compatibility  |

<Info>
  Check `GET /v1/models` with the `type=embedding` filter to see the full live list of enabled embedding models.
</Info>

## RAG with file uploads

For retrieval-augmented generation over your own documents, use the [Files & RAG](/docs/capabilities/rag) workflow — upload files, trigger embedding, and search with `POST /v1/files/search`. This is more scalable than calling the embeddings endpoint directly for large document corpora.