API 与错误码
向量与检索(embeddings)
input 的四种形状、两道容易搞混的上限、以及它和对话端点的三处不同。
POST /v1/embeddings 把文本转成向量,做检索、聚类、RAG 用。协议与 OpenAI 一致,
字段原样透传。
模型必须是向量模型
model 要选「模型与价格」页上标为向量类的那些。拿对话模型打这个端点会得到
400 model_not_supported_for_endpoint,message 里会说明它其实是哪一类 ——
这是转发前拦下的,不会白花一次上游调用。
想在程序里筛,GET /v1/models 支持一个非标准参数:?modality=embedding。
input 的四种形状
| 形状 | 例子 | 怎么算 token |
|---|---|---|
| 字符串 | "hello" |
按字符估算 |
| 字符串数组 | ["a", "b"] |
按字符估算 |
| 整数数组 | [15339, 1917] |
已经是 token,长度即真值 |
| 整数数组的数组 | [[15339], [1917]] |
各条长度之和 |
前两种我们估算 token 数,后两种你已经自己 tokenize 过了,长度就是准数。
⚠️ 两道上限,是两个不同的维度
| 上限 | 值 | 管哪种形状 |
|---|---|---|
| 条数 | 2048 | 字符串数组 / 整数数组的数组 |
| token 总数 | 2,000,000 | 整数数组 / 整数数组的数组 |
分开的理由很实际:一个 [15339, 1917, ...] 是「一条」输入,它的长度是 token 数不是条数。
拿条数上限去卡它,会把一个合法的 50 万 token 请求当成"50 万条"拒掉。
超限返回 400 invalid_request,message 里带上实际值和上限,照着改就行。
空的 input、认不出来的形状是同一个码。
与对话端点的三处不同
- 不支持流式 —— 向量是一次返回完整结果的,没有 SSE。
- 有硬超时 —— 整段处理超过时限会返回
504。此时零产出,不计费。 - 批量越大越要留意超时 —— 2048 条是上限不是建议值。上游对大批量的处理时间 不是线性的,拆成几批往往更快也更稳。
响应形状与 OpenAI 一致:
{ "object": "list",
"data": [{ "embedding": [0.1, ...], "index": 0 }],
"usage": { "prompt_tokens": 8, "total_tokens": 8 } }
计费
与对话端点同一套:按 token、实时从余额扣、失败不计费。 向量只有输入没有输出,所以只有输入那一段费用。