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

# Embeddings API：文本向量模型、维度与调用示例

> 用老张API的 /v1/embeddings 把文本转成向量：可用模型的价格与默认维度、cURL 与 Python 批量示例，以及按 index 保持顺序。

Embeddings API 把文本转成向量，请求与响应格式与 OpenAI Embeddings API 相同，可以直接使用 OpenAI SDK。

| 项目 | 内容 |
| - | - |
| 端点 | `POST https://api.laozhang.ai/v1/embeddings` |
| 请求字段 | `model` 和 `input` |
| 结果 | `data[i].embedding` 是第 `i` 条输入的向量 |
| 本页示例模型 | `text-embedding-3-small` |
| 价格与默认维度 | 见[可用模型](#可用模型) |

## 可用模型

2026 年 9 月 29 日公开价格配置中，以下模型标注了 Embeddings 端点，价格按每 1M tokens 计，以[模型与价格总表](/models)为准：

| 模型 ID | 厂商 | 价格 | 默认维度 |
| - | - | - | - |
| `text-embedding-3-small` | OpenAI | \$0.02 | 1536 |
| `text-embedding-3-large` | OpenAI | \$0.13 | 3072 |
| `text-embedding-ada-002` | OpenAI | \$0.10 | 1536 |
| `text-embedding-v4` | 阿里巴巴 | \$0.07 | [见阿里云文档](https://help.aliyun.com/zh/model-studio/embedding) |

维度的补充说明：

* OpenAI 模型的维度来自 [OpenAI 向量指南](https://developers.openai.com/api/docs/guides/embeddings)。
* 只有 `text-embedding-3-small` 和 `text-embedding-3-large` 可以用 `dimensions` 参数缩短向量，例如在请求体中加入 `"dimensions": 512`。
* `text-embedding-ada-002` 固定输出 1536 维。
* 阿里巴巴模型的默认维度和可选维度以阿里云百炼文档为准。

以上模型只接受文本输入，不能直接生成图片向量：

* 需要按内容检索图片时，先用[视觉理解](/api-capabilities/vision-understanding)模型把图片描述成文字，再对描述做嵌入。
* 不要把 Base64 图片当作 `input` 字符串传入。接口会返回向量，但它只代表这串字符，不代表图片内容。

## 发送请求

在[令牌管理](https://api.laozhang.ai/token)创建 API Key，写入环境变量；使用 Python 示例时，先执行 `python -m pip install openai`。

```bash theme={null}
export LAOZHANG_API_KEY="替换为你的老张API密钥"
```

`input` 可以是单个字符串，也可以是字符串数组。下面一次提交两段文本：

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl --fail-with-body --max-time 60 \
      "https://api.laozhang.ai/v1/embeddings" \
      -H "Authorization: Bearer $LAOZHANG_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "text-embedding-3-small",
        "input": ["老张API支持哪些向量模型？", "批量请求怎样保持输入顺序？"]
      }' \
      -o embeddings.json
    ```

    安装 jq 后，可以按 `index` 查看每条向量的维度：

    ```bash theme={null}
    jq -c '.data | sort_by(.index) | map({index, dimensions: (.embedding | length)})' embeddings.json
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os
    from openai import OpenAI

    client = OpenAI(
        api_key=os.environ["LAOZHANG_API_KEY"],
        base_url="https://api.laozhang.ai/v1",
        timeout=60.0,
        max_retries=0,
    )
    texts = ["老张API支持哪些向量模型？", "批量请求怎样保持输入顺序？"]
    response = client.embeddings.create(
        model="text-embedding-3-small",
        input=texts,
        encoding_format="float",
    )
    items = sorted(response.data, key=lambda item: item.index)
    vectors = [item.embedding for item in items]
    for text, vector in zip(texts, vectors):
        print(f"{len(vector)} 维：{text}")
    ```
  </Tab>
</Tabs>

Python 示例显式指定 `encoding_format="float"`，与 cURL 默认返回的浮点数组一致。`text-embedding-3-small` 的两条结果都应是 1536 维。

## 读取响应

响应的关键字段如下，示例把向量截短为 3 个数，实际长度等于模型维度：

```json theme={null}
{
  "object": "list",
  "model": "text-embedding-3-small",
  "data": [
    {"object": "embedding", "index": 0, "embedding": [0.0123, -0.0456, 0.0078]},
    {"object": "embedding", "index": 1, "embedding": [-0.0311, 0.0094, 0.0217]}
  ]
}
```

`data[i].index` 对应 `input` 数组中的位置。批量请求时先按 `index` 排序，再与原文配对存储，不要依赖 `data` 的排列顺序。实际扣费以[调用日志](/faq/call-logs)为准。

## 使用注意

* 不同模型、或同一模型不同维度生成的向量，不能放在同一个索引里比较；更换模型或维度后，要重新生成全部向量。
* 单次请求的条数和单条文本长度有上限，以厂商文档为准；数据量大时分批发送，每批都按 `index` 还原顺序。
* OpenAI 的向量已归一化为长度 1，余弦相似度可以直接用点积计算。

## 相关文档

* [OpenAI Embeddings 接口参考](https://developers.openai.com/api/reference/resources/embeddings/methods/create)
* [阿里云百炼向量化文档](https://help.aliyun.com/zh/model-studio/embedding)
* [模型与价格总表](/models)
* [Models API](/api-reference/models)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.