Skip to main content
POST
/
v1
/
embeddings
curl https://api.deerapi.com/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <DEERAPI_KEY>" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "番茄是一种常见食材。"
  }'
{
  "object": "<string>",
  "data": [
    {
      "object": "<string>",
      "index": 123,
      "embedding": "<unknown>"
    }
  ],
  "model": "<string>",
  "usage": {
    "prompt_tokens": 123,
    "total_tokens": 123
  }
}

​
概述

/v1/embeddings 用于把文本转换成向量。最常见的用途包括语义搜索、知识库召回、文本聚类、相似内容去重和 RAG 检索前的向量化预处理。 DeerAPI 对 OpenAI Embeddings 接口保持兼容。对于大多数接入场景，您只需要先理解 4 个字段：model、input、dimensions、encoding_format。

​
如何阅读参数表

  • model 和 input 是通用必填项，决定“用哪个嵌入模型”以及“要向量化什么内容”。
  • dimensions 只在 text-embedding-3 及更新模型上常见，适合在向量质量和存储成本之间做权衡。
  • encoding_format 默认为 float；如果您是大批量离线写库，base64 往往更节省传输体积。

​
使用建议

  • 做大规模检索或成本敏感场景时，优先考虑 text-embedding-3-small。
  • 做高质量召回、重排前粗筛或更重视语义表达时，再考虑 text-embedding-3-large。
  • 批量请求时请控制单次输入总量，避免把过多超长文本塞进一个请求里。

Authorizations

​
Authorization
string
header
required

Bearer token authentication. Use your DeerAPI key.

Body

application/json

兼容 OpenAI Embeddings。实际接入时通常只需要关心 model、input、dimensions、encoding_format 这几个字段；其余重点更多在向量库选型、切片策略和召回逻辑。

​
model
string
default:text-embedding-3-small
required

要调用的嵌入模型 ID。一般来说，text-embedding-3-small 更适合大规模检索与成本敏感场景，text-embedding-3-large 更适合追求向量质量。

​
input
default:番茄是一种常见食材。
required

要向量化的内容。可以传单条文本、批量文本数组，或已分词的 token 数组。每条输入都不能是空字符串，并且需要落在模型允许的 token 上限内；text-embedding-3 系列单条输入常见上限为 8192 tokens。

​
dimensions
integer

返回向量的维度。仅 text-embedding-3 及更新模型支持。维度越低，存储和检索成本越小；维度越高，通常保留的语义信息越多。

​
encoding_format
enum<string>
default:float

嵌入向量的返回格式。float 便于直接调试和落库；base64 更适合对传输体积敏感的大批量请求。

Available options:
float,
base64
​
user
string

最终用户标识，适合做风控、统计或多租户链路追踪。

Response

200 - application/json

Successful Response

​
object
string
required

顶层对象的类型。

​
data
object[]
required

一个包含嵌入向量对象的列表。如果输入请求了多个文本的嵌入，这个列表里就会有多个对象。

​
model
string
required

用于生成嵌入向量的具体模型名称。

​
usage
object
required

本次请求的token使用情况统计。