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

# POST /v1/embeddings — 文本向量化

> 将文本转换为向量表示，用于语义搜索和相似度计算。

`/v1/embeddings` 端点将一个或多个文本字符串转换为稠密向量表示（embedding）。你可以用这些向量进行语义相似度搜索、构建 RAG 流程、聚类文档或训练分类器。Anyone 兼容 OpenAI Embeddings API 格式，任何 OpenAI 兼容的 embedding 客户端无需修改即可使用。

***

## POST /v1/embeddings

### 请求体

<ParamField body="model" type="string" required>
  embedding 模型，例如 `text-embedding-3-small`、`text-embedding-3-large` 或 `text-embedding-ada-002`。可用模型取决于你配置的渠道。
</ParamField>

<ParamField body="input" type="string | string[]" required>
  要向量化的文本。可以是单个字符串或字符串数组。每个字符串独立向量化。数组适合在一次请求中批量处理多个文档。
</ParamField>

<ParamField body="encoding_format" type="string">
  返回的向量格式。`float` 返回浮点数数组；`base64` 返回 base64 编码的二进制字符串。默认 `float`。
</ParamField>

<ParamField body="dimensions" type="integer">
  输出向量的维度数。仅部分模型支持（如 `text-embedding-3-small` 和 `text-embedding-3-large`）。将向量截断到指定长度。
</ParamField>

<ParamField body="user" type="string">
  终端用户的可选标识符。用于服务商侧的监控和滥用检测。
</ParamField>

### 响应

<ResponseField name="object" type="string">
  始终为 `"list"`。
</ResponseField>

<ResponseField name="model" type="string">
  生成 embedding 的模型。
</ResponseField>

<ResponseField name="data" type="object[]">
  embedding 对象数组，每个输入字符串对应一个。

  <Expandable title="embedding 对象属性">
    <ResponseField name="object" type="string">
      始终为 `"embedding"`。
    </ResponseField>

    <ResponseField name="index" type="integer">
      该 embedding 在输入数组中的位置，从 `0` 开始。
    </ResponseField>

    <ResponseField name="embedding" type="number[]">
      浮点数数组形式的向量。长度等于模型输出维度，或指定 `dimensions` 后的值。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="usage" type="object">
  请求的 token 用量。

  <Expandable title="usage 属性">
    <ResponseField name="prompt_tokens" type="integer">
      输入中的 token 数量。
    </ResponseField>

    <ResponseField name="total_tokens" type="integer">
      处理的总 token 数（embedding 请求中与 `prompt_tokens` 相同）。
    </ResponseField>
  </Expandable>
</ResponseField>

***

### 示例

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.anyone.ai/v1/embeddings \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "text-embedding-3-small",
      "input": [
        "Anyone is a unified AI gateway.",
        "You can embed multiple strings in one request."
      ],
      "encoding_format": "float"
    }'
  ```

  ```python python theme={null}
  from openai import OpenAI

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

  response = client.embeddings.create(
      model="text-embedding-3-small",
      input=[
          "Anyone is a unified AI gateway.",
          "You can embed multiple strings in one request.",
      ],
  )

  for item in response.data:
      print(f"Index {item.index}: {len(item.embedding)} dimensions")
  ```
</CodeGroup>

***

## 常见用途

* **语义搜索** — 向量化文档库和用户查询，按余弦相似度排序。
* **检索增强生成（RAG）** — 在传递给语言模型前检索知识库中最相关的片段。
* **聚类** — 无需标注数据即可将语义相关的文档分组。
* **分类** — 将向量作为下游分类器的特征。