向量

POST /v1/embeddings 的请求与响应、默认开启的按条缓存，以及批量调用的限制。

更新于 2026-10-24阅读约 3 分钟

http

POST https://api.scirouter.cn/v1/embeddings

将文本转换为向量，用于检索、聚类与去重。请求与响应格式与 OpenAI Embeddings 一致。

请求

bash

curl https://api.scirouter.cn/v1/embeddings \
  -H "Authorization: Bearer $SCIROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_EMBEDDING_MODEL_ID",
    "input": ["铁电材料的畴壁迁移", "钙钛矿太阳能电池的稳定性"]
  }'

Python：

python

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["SCIROUTER_API_KEY"], base_url="https://api.scirouter.cn/v1")

resp = client.embeddings.create(
    model="YOUR_EMBEDDING_MODEL_ID",
    input=["铁电材料的畴壁迁移", "钙钛矿太阳能电池的稳定性"],
)
vectors = [item.embedding for item in resp.data]

字段	必填	说明
`model`	是	向量模型的 id，见模型中心或 `GET /models`
`input`	是	字符串、字符串数组（一次向量化多条），或 token 数组（`[1, 2, 3]` 为一条，`[[1, 2], [3]]` 为多条）
`metadata` / `user`	否	归因标签，不转给上游，见可观测性
其他字段	否	原样转给上游，如 `dimensions`、`encoding_format`，上游支持时生效

响应

json

{
  "object": "list",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [0.0123, -0.0456] },
    { "object": "embedding", "index": 1, "embedding": [0.0789, 0.0012] }
  ],
  "model": "YOUR_EMBEDDING_MODEL_ID",
  "usage": { "prompt_tokens": 24, "total_tokens": 24 },
  "scirouter": { "request_id": "req_…", "cache": "miss", "cost_quota": 480, "…": "…" }
}

数值为示例，embedding 只列出前两维。

字段	说明
`data`	按 `index` 与输入一一对应
`usage`	全部输入的 token 数，包括来自缓存的条目
`scirouter.cost_quota`	本次实际扣除的配额。按输入 token 计费，来自缓存的条目不计费
`scirouter.cache`	`hit` / `partial` / `miss` / `bypass`

按条缓存

向量接口默认开启响应缓存，每条输入分别缓存，默认保存 24 小时。命中条件为同一 API Key、同一模型，且其他参数相同（如 dimensions / encoding_format）。

同一段文字在任一批次、任一位置都能命中。
一批中只有未命中的条目发给上游，结果按原顺序拼回。此时响应头为 X-SciRouter-Cache: PARTIAL，scirouter.cache_items 给出命中的条数。
命中的条目不计费，但请求仍计入每分钟请求数。
不同 API Key 之间不共享缓存。

请求头	取值	作用
`X-SciRouter-Cache`	`disabled`	不使用缓存
`Cache-Control`	`no-store`	不使用缓存
`Cache-Control`	`no-cache`	刷新缓存，不读取旧结果

缓存规则见缓存与幂等。

批量调用

一次传入数组比逐条调用快，也更不容易触发每分钟请求数的限频。单次请求受以下限制：

限制	上限	超出时
请求体	4 MB	413 `payload_too_large`
一批输入的 token 估算	套餐的每分钟 token 上限	400 `validation_failed`，`details.reason` 为 `plan_tpm_exceeded`、`param` 为 `input`，`details.limit` 为上限、`details.estimated` 为估算
单批条数	上游通常有上限	—

列表较长时按几百条一批切分。

批量任务带上 Idempotency-Key：成功的结果保存 24 小时，同键重试直接返回该次结果（响应头 Idempotent-Replayed: true），不重复扣费，见缓存与幂等。

向量

文档目录

请验证你的身份

Cookie 偏好

必要

统计