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

# Create embeddings

> Convert text into vector embeddings for semantic search, clustering, recommendations, and retrieval.

Creates numerical vector representations of text. Vectors from the same model can be compared for semantic similarity and used in retrieval pipelines.

## Endpoint

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST https://api.yelu.ai/v1/embeddings
```

## Headers

<ParamField header="Authorization" type="string" required>
  API key using the format `Bearer $YELU_API_KEY`.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

## Request body

<ParamField body="model" type="string" required>
  An embedding-capable model ID available to your account.
</ParamField>

<ParamField body="input" type="string | string[]" required>
  Text or batch of texts to embed. Empty input and inputs beyond the model's context limit are rejected.
</ParamField>

<ParamField body="encoding_format" type="string" default="float">
  `float` for a JSON number array or `base64` for encoded vector bytes when supported.
</ParamField>

<ParamField body="dimensions" type="integer">
  Requested output dimensions on models that support shortening embeddings.
</ParamField>

<ParamField body="user" type="string">
  Stable, non-sensitive end-user identifier when accepted by the selected provider.
</ParamField>

## Response

<ResponseField name="object" type="string" required>
  Always `list`.
</ResponseField>

<ResponseField name="data" type="array" required>
  One embedding per input, in input order. Each item contains `object`, `index`, and `embedding`.
</ResponseField>

<ResponseField name="model" type="string" required>
  Model used to create the vectors.
</ResponseField>

<ResponseField name="usage" type="object">
  Token accounting with `prompt_tokens` and `total_tokens` when supplied.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl https://api.yelu.ai/v1/embeddings \
    -H "Authorization: Bearer $YELU_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "text-embedding-3-small",
      "input": [
        "Reliable APIs return structured errors.",
        "Good interfaces fail predictably."
      ],
      "encoding_format": "float"
    }'
  ```

  ```javascript JavaScript (Fetch) theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('https://api.yelu.ai/v1/embeddings', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.YELU_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'text-embedding-3-small',
      input: [
        'Reliable APIs return structured errors.',
        'Good interfaces fail predictably.',
      ],
      encoding_format: 'float',
    }),
  });

  if (!response.ok) throw new Error(await response.text());
  const data = await response.json();
  console.log(data.data.map((item) => item.embedding.length));
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import os
  import requests

  response = requests.post(
      "https://api.yelu.ai/v1/embeddings",
      headers={"Authorization": f"Bearer {os.environ['YELU_API_KEY']}"},
      json={
          "model": "text-embedding-3-small",
          "input": [
              "Reliable APIs return structured errors.",
              "Good interfaces fail predictably.",
          ],
          "encoding_format": "float",
      },
      timeout=60,
  )
  response.raise_for_status()
  print([len(item["embedding"]) for item in response.json()["data"]])
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "object": "list",
    "data": [
      {
        "object": "embedding",
        "index": 0,
        "embedding": [0.01241, -0.00728, 0.03155, -0.01902]
      },
      {
        "object": "embedding",
        "index": 1,
        "embedding": [0.01087, -0.00691, 0.03088, -0.01794]
      }
    ],
    "model": "text-embedding-3-small",
    "usage": {
      "prompt_tokens": 14,
      "total_tokens": 14
    }
  }
  ```

  ```json 400 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "error": {
      "message": "Input must not be empty.",
      "type": "invalid_request_error",
      "param": "input",
      "code": "invalid_value"
    }
  }
  ```
</ResponseExample>

## Error codes

| Status      | Code or type            | Meaning                                                                 |
| ----------- | ----------------------- | ----------------------------------------------------------------------- |
| `400`       | `invalid_request_error` | Empty, oversized, or invalid input; unsupported dimensions or encoding. |
| `401`       | `authentication_error`  | Missing or invalid API key.                                             |
| `403`       | `permission_denied`     | The embedding model is not enabled.                                     |
| `404`       | `model_not_found`       | Model ID is unavailable.                                                |
| `413`       | `request_too_large`     | Batch or request body is too large.                                     |
| `429`       | `rate_limit_error`      | Request limit reached.                                                  |
| `500`–`504` | `server_error`          | Temporary gateway or upstream failure.                                  |

<Warning>
  Do not compare vectors produced by different models or dimension settings. Re-embed the entire corpus when you change either one, and version the index metadata alongside the vectors.
</Warning>