创建 Embeddings 请求导读
Embeddings 解决的是检索、相似度、聚类和索引，不是生成。先把用途分清，很多误用就会自然消失。
POST/v1/embeddings
embeddings 接口最容易被误用成“另一种生成 API”。实际上它的职责更底层： 把文本映射成向量，用于检索、RAG、去重、相似度和聚类。你要先分清 检索任务 和 生成任务，接口选择才不会错。
最值得先看的参数
| Name | Type | Required | Description |
|---|---|---|---|
model | string | Required | embeddings 模型标识。不要直接沿用选择生成模型的方式来选它。 |
input | string | string[] | Required | 单条或批量输入。批量时返回顺序会和输入顺序对应。 |
encoding_format | string | 向量编码格式。对接下游向量库时要确认格式要求。 | |
dimensions | integer | 目标维度。只有部分模型支持缩维，不要默认每个模型都能改。 | |
user | string | 可选归因字段。适合做内部追踪，不是业务主键。 |
最小请求
bash
curl -X POST https://api.therouter.ai/v1/embeddings \
-H "Authorization: Bearer $THEROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "zhipu/embedding-3",
"input": [
"incident postmortem",
"deploy rollback checklist"
]
}'Cohere 图片向量
文本仍按原方式传字符串。图片使用 image_url 对象；直接传 URL 字符串会被当作文本。 URL 可以是公网图片地址、Base64 data URI，或通过 /v1/files 上传且属于当前租户的文件 ID。
json
{
"model": "cohere/embed-v4",
"input": [{"type":"image_url","image_url":{"url":"https://httpbin.org/image/png"}}],
"input_type": "search_document",
"dimensions": 256
}向 POST /v1/embeddings 发送以上 JSON。支持 PNG、JPEG、GIF、WebP，单张不超过 5 MB， 每次最多 96 项。文本和图片在数组中分别生成向量，不支持将它们融合成单个向量或直接输入 PDF。 图片价格为 TheRouter 平台价每百万 token $0.47；返回的 usage.image_tokens 已包含在 usage.prompt_tokens 中。input_type 默认为 search_document， 查询向量可使用 search_query；维度可选 256、512、1024 或 1536。 目前 truncate 参数不会转发，请勿依赖。
批量输入的关键语义
批量 embeddings 的返回顺序会对应输入顺序。这意味着你应该把索引、原始文本和返回向量一起保存， 不要假设下游系统会替你自动做正确映射。
什么时候它是正确选择
- 你在做检索、RAG、相似度搜索或文档聚类。
- 你需要把文本内容映射成可检索向量，而不是直接生成回答。
- 你想把上游 OpenAI-compatible embeddings 调用迁到统一路由层。
最容易犯的错
text
1. 用 embeddings 接口做生成任务。
2. 批量输入后没有保留输入顺序映射。
3. 直接沿用选择生成模型的方式去选 embeddings 模型。
4. dimensions 改了，却没确认下游索引结构是否同步更新。