文档

Embeddings

更新于 2026-10-02

RokoAPI 提供 OpenAI 兼容的文本嵌入接口，可直接用于语义搜索、RAG、聚类、分类和相似度计算。

端点

POST https://api.rokoapi.com/v1/embeddings

请求使用普通 API Key：

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

可用模型

模型 ID	默认 / 最大维度	输入价格
`text-embedding-3-large`	3072	$0.0350267225 / 百万输入 Token

计费只统计响应 usage.prompt_tokens 对应的输入 Token。目录页面为了展示会把单价舍入到 9 位小数；实际扣费使用后台保存的完整价格表达式。最新价格以模型定价为准。

最小请求

curl https://api.rokoapi.com/v1/embeddings \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-large",
    "input": "RokoAPI 提供统一的 AI API 接口。"
  }'

请求字段

字段	类型	必填	规则
`model`	string	是	只能使用上表中的精确模型 ID
`input`	string 或 string[]	是	非空文本，或 1–2048 条非空文本；不接受整数 Token 数组
`dimensions`	integer	否	必须大于 0；最大 3072，省略时默认 3072
`encoding_format`	string	否	`float` 或 `base64`；省略时使用上游默认格式
`user`	string	否	调用方用于标识最终用户的字符串

该端点不支持流式返回。数组输入会按原顺序返回多个结果，可用每一项的 index 与输入对应。

批量请求

{
  "model": "text-embedding-3-large",
  "input": ["如何重置 API Key？", "如何查看模型价格？"],
  "dimensions": 1024,
  "encoding_format": "float"
}

批量仅减少网络往返，不会把多条文本合并成一个向量。单次最多传 2048 条；更大的数据集应在客户端分批，并为失败批次单独重试。

SDK 示例

Python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.rokoapi.com/v1",
)

response = client.embeddings.create(
    model="text-embedding-3-large",
    input=["第一段文本", "第二段文本"],
    dimensions=1024,
    encoding_format="float",
)

for item in response.data:
    print(item.index, len(item.embedding), item.embedding[:5])
print(response.usage.prompt_tokens, response.usage.total_tokens)

JavaScript / TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ROKOAPI_API_KEY,
  baseURL: "https://api.rokoapi.com/v1",
});

const response = await client.embeddings.create({
  model: "text-embedding-3-large",
  input: ["第一段文本", "第二段文本"],
  dimensions: 1024,
  encoding_format: "float",
});

for (const item of response.data) {
  console.log(item.index, item.embedding.length, item.embedding.slice(0, 5));
}
console.log(response.usage);

API Key 只能保存在服务端，不要放入浏览器、移动端安装包或公开仓库。

响应结构

float 格式返回标准 OpenAI 兼容结构：

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0123, -0.0456, 0.0789]
    }
  ],
  "model": "text-embedding-3-large",
  "usage": {
    "prompt_tokens": 9,
    "total_tokens": 9
  }
}

实际向量长度由模型默认维度或请求中的 dimensions 决定，示例数组已截短。使用 base64 时，embedding 按兼容协议返回编码后的字符串；存储前应按所用 OpenAI SDK的处理方式解码。

向量使用规则

同一个向量索引必须统一模型和维度，不能混用 Small、Large 或不同 dimensions 的结果。
修改模型或维度后，需要重新生成并写入全部向量。
相似度搜索通常使用余弦相似度；入库前是否归一化应与向量数据库的距离函数保持一致。
建议保存模型 ID、维度和源文本版本，便于后续重建索引。
日志中不要保存包含敏感数据的完整输入文本或向量。

错误处理

参数不合法时返回 400，例如空文本、超过 2048 条、未知 encoding_format 或维度超出模型上限。认证、余额、限流和上游错误遵循统一错误结构，详见错误码与速率限制。

只对超时、限流和暂时性 5xx 错误进行有限次数的指数退避重试；不要对确定性的 400 参数错误重复请求。

端点