> ## 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.

# 创建 Embedding

> 将文本转换为向量，用于语义搜索、聚类、推荐与检索增强生成。

创建文本的数值向量表示。同一模型产生的向量可用于语义相似度比较与检索。

## 端点

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

## 请求头

<ParamField header="Authorization" type="string" required>格式为 `Bearer $YELU_API_KEY`。</ParamField>
<ParamField header="Content-Type" type="string" required>必须为 `application/json`。</ParamField>

## 请求体

<ParamField body="model" type="string" required>账号可用的 Embedding 模型 ID。</ParamField>
<ParamField body="input" type="string | string[]" required>单段文本或文本数组。空输入和超过模型上下文限制的输入会被拒绝。</ParamField>
<ParamField body="encoding_format" type="string" default="float">`float` 返回数字数组；兼容模型可用 `base64`。</ParamField>
<ParamField body="dimensions" type="integer">支持缩短向量的模型可指定输出维度。</ParamField>
<ParamField body="user" type="string">稳定且不敏感的用户标识。</ParamField>

## 响应

<ResponseField name="object" type="string" required>固定为 `list`。</ResponseField>
<ResponseField name="data" type="array" required>与输入顺序一致的向量数组，每项包含 `object`、`index` 与 `embedding`。</ResponseField>
<ResponseField name="model" type="string" required>生成向量的模型。</ResponseField>
<ResponseField name="usage" type="object">Token 用量。</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":["可靠的 API 返回结构化错误。","优秀的接口会以可预测方式失败。"],"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: ['可靠的 API 返回结构化错误。', '优秀的接口会以可预测方式失败。'], encoding_format: 'float' }),
  });
  if (!response.ok) throw new Error(await response.text());
  console.log((await response.json()).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": ["可靠的 API 返回结构化错误。", "优秀的接口会以可预测方式失败。"], "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":18,"total_tokens":18}}
  ```

  ```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>

## 错误码

| 状态码         | 含义                |
| ----------- | ----------------- |
| `400`       | 输入为空、过大，或维度/编码不支持 |
| `401`       | Key 缺失或无效         |
| `403`       | Embedding 模型未开启   |
| `404`       | 模型不可用             |
| `413`       | Batch 或请求体过大      |
| `429`       | 达到请求限制            |
| `500`–`504` | 网关或上游临时失败         |

<Warning>不要比较不同模型或不同维度产生的向量。切换配置时应重新生成整个语料库的向量，并在索引元数据中记录版本。</Warning>