向量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)响应。
请求体#
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 必填 | 型号 ID |
input | string | array | 必填(批量文件型号除外) | 待向量化的内容,写法见上表。平台验收示例只覆盖文本;多模态型号的图片元素按厂商格式书写(千问多模态 { "image": "https://…" },豆包 { "type": "image_url", "image_url": { "url": "https://…" } }),以厂商文档为准 |
parameters | object | 可选 | 千问:厂商原生参数,例如 text_type、dimension,以厂商文档为准 |
file_url | string | 批量文件型号必填 | 仅 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[].embedding | usage |
| 智谱 | data[].embedding | usage |
| 豆包 | data.embedding | usage |
千问响应示例
{
"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": ["向量检索通过向量相似度查找相关内容。", "今天的午餐是米饭。"]
}'import os
import uuid
import requests
response = requests.post(
"https://api.tokentosea.com/v1/embeddings",
headers={
"Authorization": "Bearer " + os.environ["TOKENTOSEA_API_KEY"],
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"model": "text-embedding-v4",
"input": ["向量检索通过向量相似度查找相关内容。", "今天的午餐是米饭。"],
},
timeout=120,
)
response.raise_for_status()
body = response.json()
vectors = [item["embedding"] for item in body["output"]["embeddings"]] # 千问原生结构
print(len(vectors), len(vectors[0]), body["usage"])import { randomUUID } from 'node:crypto';
const response = await fetch('https://api.tokentosea.com/v1/embeddings', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.TOKENTOSEA_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': randomUUID(),
},
body: JSON.stringify({
model: 'text-embedding-v4',
input: ['向量检索通过向量相似度查找相关内容。', '今天的午餐是米饭。'],
}),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const body = await response.json();
const vectors = body.output.embeddings.map((item) => item.embedding); // 千问原生结构
console.log(vectors.length, vectors[0].length, body.usage);其他厂商的请求体:
{ "model": "embedding-3", "input": ["你好世界"] }{ "model": "doubao-embedding-vision-251215", "input": [{ "type": "text", "text": "你好世界" }] }{ "model": "qwen3-vl-embedding", "input": [{ "text": "你好世界" }] }{ "model": "text-embedding-async-v1", "file_url": "https://example.com/lines.txt", "parameters": { "text_type": "document" } }批量文件型号返回 202,按结果查询轮询。
错误#
| 状态码 | code | 原因与处理 |
|---|---|---|
422 | embedding_file_url_required | text-embedding-async-v1 缺少 file_url |
422 | embedding_file_limit、embedding_line_byte_limit、utf8_text_required | 批量文件不符合限制 |
422 | input_media_unavailable | file_url 无法下载 |
409 | idempotency_conflict | 批量文件型号:同一个键对应了不同请求 |
422 | response_mode_not_verified | 本接口不支持流式 |