TokenToSea开发者文档
控制台

向量POST

把文本(以及多模态型号的图片)转为向量,用于检索与相似度计算;支持按文件批量生成向量的异步型号。

本页内容

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

生成向量。请求使用统一的 model + input 字段,平台转换成各厂商的原生向量接口,响应是厂商的原生结构,不同厂商的字段不同(见响应)。

前提:全能密钥或模型密钥,账户可用余额足以覆盖本次预留。Python 示例需要 pip install requests,Node.js 示例需要 Node.js 18+。

支持的型号#

截至 2026-10-21,17 个型号开放本接口,以 GET /v1/models 为准。

服务商型号input 写法
千问(文本)text-embedding-v4、text-embedding-v3、text-embedding-v2、text-embedding-v1、qwen3.7-text-embedding、qwen3.7-text-embedding-flash字符串或字符串数组
千问(多模态)qwen3-vl-embedding、qwen2.5-vl-embedding、multimodal-embedding-v1、tongyi-embedding-vision-plus、tongyi-embedding-vision-plus-2026-03-06、tongyi-embedding-vision-flash、tongyi-embedding-vision-flash-2026-03-06对象数组,例如 [{ "text": "…" }]
千问(批量文件)text-embedding-async-v1不使用 input,改用 file_url,异步
智谱embedding-3、embedding-2字符串或字符串数组(智谱原生格式)
豆包doubao-embedding-vision-251215带类型的对象数组,例如 [{ "type": "text", "text": "…" }]

只支持非流式(JSON)响应。

请求体#

参数类型必填说明
modelstring必填型号 ID
inputstring | array必填(批量文件型号除外)待向量化的内容,写法见上表。平台验收示例只覆盖文本;多模态型号的图片元素按厂商格式书写(千问多模态 { "image": "https://…" },豆包 { "type": "image_url", "image_url": { "url": "https://…" } }),以厂商文档为准
parametersobject可选千问:厂商原生参数,例如 text_type、dimension,以厂商文档为准
file_urlstring批量文件型号必填仅 text-embedding-async-v1:UTF-8 文本文件 URL,每行一条
其他字段—可选智谱、豆包请求体原样转发(例如智谱的 dimensions),以厂商文档为准

批量文件限制#

text-embedding-async-v1 由平台先下载 file_url 的文件、校验后存入私有存储,再交给厂商:

限制值超出时
文件大小75 MiB请求失败,不扣费
可访问性URL 必须能从公网下载422 input_media_unavailable
编码UTF-8,不能包含 NUL 字符422 utf8_text_required / embedding_file_limit
行数最多 100,000 行,至少 1 行非空422 embedding_file_limit
单行长度每个非空行最多 2,046 个 UTF-8 字节422 embedding_line_byte_limit

预留费用按「非空行数 × 2048 token」计算,完成后按厂商返回的用量结算。结果文件转存到私有存储,在结果的 output.data[] 中提供下载链接。同一个幂等键重复提交同一文件返回原任务;请求体不同返回 409 idempotency_conflict。

响应#

返回厂商原生结构,向量所在位置不同:

服务商向量位置用量
千问output.embeddings[].embeddingusage
智谱data[].embeddingusage
豆包data.embeddingusage
千问响应示例
{
  "output": {
    "embeddings": [{ "text_index": 0, "embedding": [0.0123, -0.0456, "…"] }]
  },
  "usage": { "total_tokens": 4 },
  "request_id": "…"
}

字段名以厂商文档为准;结算使用厂商返回的输入 token(多模态型号另计图片 token)。厂商未返回可核验的用量时,调用进入待核对,不按估算扣费。

示例#

curl https://api.tokentosea.com/v1/embeddings \
  -H "Authorization: Bearer $TOKENTOSEA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "text-embedding-v4",
    "input": ["向量检索通过向量相似度查找相关内容。", "今天的午餐是米饭。"]
  }'

其他厂商的请求体:

{ "model": "embedding-3", "input": ["你好世界"] }

批量文件型号返回 202,按结果查询轮询。

错误#

状态码code原因与处理
422embedding_file_url_requiredtext-embedding-async-v1 缺少 file_url
422embedding_file_limit、embedding_line_byte_limit、utf8_text_required批量文件不符合限制
422input_media_unavailablefile_url 无法下载
409idempotency_conflict批量文件型号:同一个键对应了不同请求
422response_mode_not_verified本接口不支持流式

下一步#

    输入关键词搜索全部文档与模型。