API 示例API REFERENCE

嵌入模型（Embedding）

Embedding 接口把文本转换为向量，适合语义搜索、知识库召回、去重和相似度计算。

统一 API Endpointhttps://api.tokensapi.cn/v1POST /embeddings

认证方式Bearer API Key

响应协议JSON

调用入口统一网关

请求接口

请求地址固定，请根据当前页面的参数说明替换模型 ID 和业务输入。

POST${base_url}/embeddings

Header 参数

Embedding 请求使用 Bearer API Key 鉴权，并以 JSON 发送请求体。

参数	类型	必填	默认值	说明
`Authorization`	`string`	是	—	在 Bearer 后拼接当前工作空间的 API Key。可选值 / 约束：Bearer <API_KEY>。
`Content-Type`	`string`	是	`application/json`	请求体使用 JSON 格式。

Body 参数

输入可以是单条文本或文本数组；模型和维度要在建库、查询等链路中保持一致。

参数	类型	必填	默认值	说明
`model`	`string`	是	—	模型广场中的 Embedding 模型 ID，区分大小写。可选值 / 约束：精确复制模型详情页当前可用的 model ID。
`input`	`string \| string[] \| integer[] \| integer[][]`	是	—	需要转换为向量的文本或模型支持的 token 数组。可选值 / 约束：批量输入时，数组中每一项对应 data 中的一个向量。
`encoding_format`	`string`	否	`float`	向量编码格式。可选值 / 约束：仅支持 float；base64 返回 HTTP 400。
`dimensions`	`integer`	否	—	返回向量的维度。可选值 / 约束：必须为正数，且仅部分模型支持。
`user`	`string`	否	—	可选的最终用户标识。可选值 / 约束：不要放入 API Key 或敏感个人信息。
`extra_body`	`object`	否	—	统一 API 的扩展字段。可选值 / 约束：provider。
`extra_body.provider`	`object`	否	—	服务商选择、过滤、排序及指标范围。可选值 / 约束：筛选应用顺序：ignore → ranges → only → sort → order。
`extra_body.provider.only`	`string[]`	否	—	服务商白名单，仅在指定集合内选择。可选值 / 约束：服务商名称区分大小写。
`extra_body.provider.ignore`	`string[]`	否	—	服务商黑名单，从候选集合中排除。可选值 / 约束：非空 only 与 ignore 不得重叠；校验失败返回 HTTP 400 / invalid_request。
`extra_body.provider.order`	`string[]`	否	—	在最后提升指定服务商的优先顺序。可选值 / 约束：服务商名称区分大小写。
`extra_body.provider.sort`	`string \| string[]`	否	—	服务商排序策略，支持多个关键字，数组前面的优先级更高。可选值 / 约束：input_price、output_price、throughput、latency、input_length。
`extra_body.provider.input_price_range`	`[number, number]`	否	—	限制当前账号的输入价格范围。可选值 / 约束：单位：USD / 百万 tokens；必须恰好两个非负值且下界不大于上界。
`extra_body.provider.output_price_range`	`[number, number]`	否	—	限制当前账号的输出价格范围。可选值 / 约束：单位：USD / 百万 tokens；range=[] 非法。
`extra_body.provider.throughput_range`	`[number, number]`	否	—	限制实时吞吐范围。可选值 / 约束：单位：tokens/s。
`extra_body.provider.latency_range`	`[number, number]`	否	—	限制实时延迟范围。可选值 / 约束：单位：秒。
`extra_body.provider.input_length_range`	`[number, number]`	否	—	限制服务商支持的最大输入长度范围。可选值 / 约束：单位：Token。
`extra_body.provider.allow_fallbacks`	`boolean`	否	—	非空 only 时默认 false；否则默认 true。可选值 / 约束：true 只可放宽 only、range、sort、order；不会放宽 ignore、权限、端点能力或通道可用性。

返回结构

返回结构兼容 OpenAI Embeddings API，并附加实际路由服务商信息。

参数	类型	必填	默认值	说明
`model`	`string`	否	—	本次请求实际使用的模型 ID。
`data`	`array`	否	—	向量结果数组，与 input 数组中的文本按 index 对应。
`data[].object`	`string`	否	—	向量对象类型。可选值 / 约束：embedding。
`data[].embedding`	`number[]`	否	—	浮点向量数据。
`data[].index`	`integer`	否	—	该向量对应的输入序号，从 0 开始。
`usage.prompt_tokens`	`integer`	否	—	协议返回时的输入 Token 数量。
`usage.total_tokens`	`integer`	否	—	本次调用统计的总 Token 数量。
`provider`	`string`	否	—	实际承载请求的服务商通道信息。可选值 / 约束：仅非流式 JSON 中可能出现。

输入与维度

input 可以是单条文本或文本数组。dimensions 只有部分模型支持；建库、查询和重建索引必须使用相同模型、维度与预处理规则。

路由与计费

路由统一放在 extra_body.provider。allow_fallbacks=false 时只在 only 与各项 range 形成的候选集合内路由；为 true 且首选集合为空时可放宽 only、range、sort、order，但永不放宽 ignore、模型权限、端点能力或通道可用性。

检索链路建议

写入前统一文本切分、清洗并记录文档版本；查询和写入使用相同模型、维度与预处理规则。

仅在模型详情页确认支持时传入 dimensions 或 token-array 输入。

调用示例

示例使用占位符，请替换为模型详情页中当前可用的 model ID，并将 API Key 保存在服务端环境变量中。

curl https://api.tokensapi.cn/v1/embeddings \
  -H "Authorization: Bearer $TOKEN_MARKET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<MODEL_ID>",
    "input": ["First document for embedding", "Second document for embedding"],
    "encoding_format": "float",
    "dimensions": 1536,
    "extra_body": {
      "provider": {
        "sort": ["throughput"],
        "latency_range": [0, 2]
      }
    }
  }'

本页是否有帮助？

JSON 模式

重排序模型（Reranker）

参数

类型

必填

默认值

说明

Authorization

string

是

—

在 Bearer 后拼接当前工作空间的 API Key。

可选值 / 约束：Bearer <API_KEY>。

Content-Type

string

是

application/json

请求体使用 JSON 格式。

参数

类型

必填

默认值

说明

model

string

是

—

模型广场中的 Embedding 模型 ID，区分大小写。

可选值 / 约束：精确复制模型详情页当前可用的 model ID。

input

string | string[] | integer[] | integer[][]

是

—

需要转换为向量的文本或模型支持的 token 数组。

可选值 / 约束：批量输入时，数组中每一项对应 data 中的一个向量。

encoding_format

string

否

float

向量编码格式。

可选值 / 约束：仅支持 float；base64 返回 HTTP 400。

dimensions

integer

否

—

返回向量的维度。

可选值 / 约束：必须为正数，且仅部分模型支持。

user

string

否

—

可选的最终用户标识。

可选值 / 约束：不要放入 API Key 或敏感个人信息。

extra_body

object

否

—

统一 API 的扩展字段。

可选值 / 约束：provider。

extra_body.provider

object

否

—

服务商选择、过滤、排序及指标范围。

可选值 / 约束：筛选应用顺序：ignore → ranges → only → sort → order。

extra_body.provider.only

string[]

否

—

服务商白名单，仅在指定集合内选择。

可选值 / 约束：服务商名称区分大小写。

extra_body.provider.ignore

string[]

否

—

服务商黑名单，从候选集合中排除。

可选值 / 约束：非空 only 与 ignore 不得重叠；校验失败返回 HTTP 400 / invalid_request。

extra_body.provider.order

string[]

否

—

在最后提升指定服务商的优先顺序。

可选值 / 约束：服务商名称区分大小写。

extra_body.provider.sort

string | string[]

否

—

服务商排序策略，支持多个关键字，数组前面的优先级更高。

可选值 / 约束：input_price、output_price、throughput、latency、input_length。

extra_body.provider.input_price_range

[number, number]

否

—

限制当前账号的输入价格范围。

可选值 / 约束：单位：USD / 百万 tokens；必须恰好两个非负值且下界不大于上界。

extra_body.provider.output_price_range

[number, number]

否

—

限制当前账号的输出价格范围。

可选值 / 约束：单位：USD / 百万 tokens；range=[] 非法。

extra_body.provider.throughput_range

[number, number]

否

—

限制实时吞吐范围。

可选值 / 约束：单位：tokens/s。

extra_body.provider.latency_range

[number, number]

否

—

限制实时延迟范围。

可选值 / 约束：单位：秒。

extra_body.provider.input_length_range

[number, number]

否

—

限制服务商支持的最大输入长度范围。

可选值 / 约束：单位：Token。

extra_body.provider.allow_fallbacks

boolean

否

—

非空 only 时默认 false；否则默认 true。

可选值 / 约束：true 只可放宽 only、range、sort、order；不会放宽 ignore、权限、端点能力或通道可用性。

参数

类型

必填

默认值

说明

model

string

否

—

本次请求实际使用的模型 ID。

data

array

否

—

向量结果数组，与 input 数组中的文本按 index 对应。

data[].object

string

否

—

向量对象类型。

可选值 / 约束：embedding。

data[].embedding

number[]

否

—

浮点向量数据。

data[].index

integer

否

—

该向量对应的输入序号，从 0 开始。

usage.prompt_tokens

integer

否

—

协议返回时的输入 Token 数量。

usage.total_tokens

integer

否

—

本次调用统计的总 Token 数量。

provider

string

否

—

实际承载请求的服务商通道信息。

可选值 / 约束：仅非流式 JSON 中可能出现。

curl https://api.tokensapi.cn/v1/embeddings \ -H "Authorization: Bearer $TOKEN_MARKET_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "<MODEL_ID>", "input": ["First document for embedding", "Second document for embedding"], "encoding_format": "float", "dimensions": 1536, "extra_body": { "provider": { "sort": ["throughput"], "latency_range": [0, 2] } } }'