多模态内容检索接口文档
给文本、图片或视频按标签打分,返回分数和判定理由。文本和图片同步返回;视频或带回调时异步,完成后查询或回调。按次计费。
给一段文本、一张或多张图片、或一个视频,返回它命中了哪些标签,以及每个标签的分数和判定理由。适用产品:retrieval(多模态内容检索·全量打分),按次计费。
标签由能力方维护(例如「古装」「都市」「爱情」「自然风景」)。调用方只传标签名,不传任何内部 id。每个客户账号绑定一个标签组;不传 tags 时,按绑定组里的全部标签打分。返回的是结构化结果,没有图片或视频产物。
| 方法与路径 | 说明 |
|---|---|
POST /api/retrieval/score | 发起检索打分。文本、图片同步返回;视频或带回调时异步 |
GET /api/tasks/{request_id} | 查询异步任务 |
| 环境 | 根地址 |
|---|---|
| 测试 | https://test-star-api.aiaibase.com |
| 正式 | https://star-api.aiaibase.com |
路径接在根地址后面。例如正式环境发起检索:
POST https://star-api.aiaibase.com/api/retrieval/score请求体为 JSON,Content-Type: application/json,字符集 UTF-8。认证只使用请求头:
Authorization: Bearer {API Key}{API Key} 由能力方开通账号后下发(形如 48 位字符串),只在服务端保存,不要写进前端代码或仓库。前端不要直连本接口:由你们后端代理转发,Key 不外泄,也便于统一重试与告警。
texts、images、video 至少提供一项,可以同时传。视频和文本一起传时,会一起参与打分。
请求参数
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
texts | 三选一 | array | 文本数组,最多 100 条,每条不超过 2000 字 |
texts[].text | 是 | string | 文本内容,不能为空 |
texts[].weight | 否 | number | 该条文本的权重,正数。用于多段文本时的参考排序 |
images | 三选一 | string[] | 图片 URL 数组,最多 20 张 |
video | 三选一 | string | 视频 URL,单个。见素材要求 |
tags | 否 | string[] | 指定候选标签名,最多 50 个。与 tag_group 二选一 |
tag_group | 否 | string | 标签组名。只做一致性校验,必须等于账号绑定的组名 |
threshold | 否 | number | 分数阈值,0~1。传了只返回大于等于阈值的标签;不传返回全部候选 |
client_request_id | 异步必填 | string | 调用方请求号。同一 Key 下相同值只算一次 |
notice_url | 否 | string | 完成回调地址。填了即转异步,且必须同时传 client_request_id |
表以外的字段会被忽略,不会报错。请按上表拼装。
同步还是异步
| 触发条件 | 行为 | 返回 |
|---|---|---|
只有 texts / images | 同步 | 直接返回打分结果(实测 2~5 秒;最多 300 秒) |
带 video | 异步 | 立即返回 status=accepted,用 request_id 查询 |
带 notice_url | 异步 | 同上,完成后另回调 notice_url |
同步调用请把客户端超时设为不少于 350 秒。候选标签多、素材大时会跑到几十秒。
threshold
- 传
threshold:只返回达到阈值的标签。一个都没达到时返回tags: [],这是成功,不是失败。 - 不传
threshold:不做筛选,返回全部候选标签。没命中的会以score: 0、reason: "无证据"出现。
只需要命中结果时,请传 threshold(建议从 0.5 起)。
请求示例
同步,指定标签:
curl -X POST 'https://star-api.aiaibase.com/api/retrieval/score' \
-H 'Authorization: Bearer {API Key}' \
-H 'Content-Type: application/json' \
-d '{
"texts": [{"text": "古装宫廷里的复仇故事,女主是长发"}],
"tags": ["古装", "都市", "爱情"],
"threshold": 0.5
}'不传 tags,使用账号绑定组里的全部标签:
curl -X POST 'https://star-api.aiaibase.com/api/retrieval/score' \
-H 'Authorization: Bearer {API Key}' \
-H 'Content-Type: application/json' \
-d '{
"texts": [{"text": "都市爱情剧,女主在写字楼里遇到前任"}],
"threshold": 0.4
}'异步,视频:
curl -X POST 'https://star-api.aiaibase.com/api/retrieval/score' \
-H 'Authorization: Bearer {API Key}' \
-H 'Content-Type: application/json' \
-d '{
"video": "https://example.com/videos/a.m3u8",
"tags": ["自然风景", "都市"],
"threshold": 0.5,
"client_request_id": "req-20261113-0001",
"notice_url": "https://your.host/hooks/retrieval"
}'文本和图片在同一次请求里返回打分结果。
{
"success": true,
"data": {
"request_id": "b61a69a8-73a0-4023-a7ef-3539526881d2",
"status": "succeeded",
"model_version": "retrieval-v1.0",
"threshold": 0.5,
"tags": [
{
"tag_name": "古装",
"score": 1,
"reason": "文本明确提到“古装宫廷”,符合判定标准。"
}
],
"stats": {
"scene": "text",
"tag_count": 3,
"returned_count": 1,
"image_count": 0,
"frame_count": 0,
"elapsed_ms": 1956
}
},
"meta": {
"request_id": "b61a69a8-73a0-4023-a7ef-3539526881d2",
"timestamp": "2026-11-13T16:50:00+08:00"
}
}| 字段 | 说明 |
|---|---|
status | succeeded 成功;failed 失败(看 error) |
tags[] | 命中的标签,按分数从高到低 |
tags[].tag_name | 标签名,就是请求里传的名字,或绑定组里的名字 |
tags[].score | 0~1,越大越确定 |
tags[].reason | 判定理由(中文,可直接展示或用于调试) |
stats.scene | 打分场景:text、image、video |
stats.tag_count | 本次参与打分的候选标签数 |
stats.returned_count | 达到阈值返回的标签数 |
stats.image_count | 图片张数。文本为 0 |
stats.frame_count | 视频抽帧数。文本为 0 |
stats.elapsed_ms | 上游处理耗时(毫秒) |
model_version | 上游模型版本,排查问题时带上它 |
threshold | 回显本次生效的阈值。没传则为 null |
0 命中也是成功(HTTP 200):
{
"success": true,
"data": {
"status": "succeeded",
"tags": [],
"threshold": 0.8,
"stats": {
"returned_count": 0
}
}
}带 video 或 notice_url 提交后立即返回受理结果。此时还没有打分结论。request_id 在 meta.request_id,data 里没有。
{
"success": true,
"data": {
"status": "accepted",
"client_request_id": "req-20261113-0001"
},
"meta": {
"request_id": "31cc962a-0000-0000-0000-000000000000",
"timestamp": "2026-11-13T16:50:00+08:00"
}
}用 meta.request_id 查询,鉴权头与提交接口相同:
GET /api/tasks/{request_id}
Authorization: Bearer {API Key}返回结构与同步成功相同。
data.status | 含义 | 后续动作 |
|---|---|---|
accepted / pending / running | 排队或处理中 | 每 3~10 秒轮询,建议上限 6 分钟 |
succeeded | 完成(含 tags: []) | 取 tags 展示 |
failed | 失败 | 看 error.code,按错误码处理 |
前端处理:
- 后端拼
POST /api/retrieval/score。 - 同步返回(文本、图片):直接拿到
tags。 - 异步返回(视频或回调):拿
meta.request_id,进入处理中。 - 每 3~10 秒调
GET /api/tasks/{request_id}。succeeded后渲染tags;tags: []渲染为「未命中任何标签」。 failed时按错误码文案提示。不要自动重试 4xx。
任务进入终态(succeeded 或 failed)后,会向 notice_url POST 一次结果,结构与同步成功一致。请返回 HTTP 2xx,否则我方会重试。
回调地址必须公网可访问。回调失败不影响任务结果,可随时用 GET /api/tasks/{request_id} 兜底查询。
- 相同
client_request_id加相同请求体:直接返回首次的结果,不重复计费。 - 相同
client_request_id加不同请求体:409/4003(重复提交,请换 id)。 - 幂等键是
(token, client_request_id),不设过期时间。同一个 id 永远只对应第一次的结果。 - 同步接口只在网络超时时重试,且必须复用同一个
client_request_id。
失败时返回:
{
"success": false,
"message": "...",
"error": {
"code": 1001,
"message": "..."
},
"meta": {}
}message 给开发者看,可直接打日志。给最终用户展示时请换成人话,例如 4107 展示为「素材读取失败,请换一个链接」。
| HTTP | code | 含义 | 处理 |
|---|---|---|---|
| 401 | 5003 | 认证信息无效 | 检查 Key 是否被环境用错 |
| 401 | 5301 | 令牌已过期 | 换新 Key |
| 401 | 5304 | 令牌已被撤销 | 联系能力方 |
| 402 | 9903 | 余额不足 | 充值后再调。本次不计费 |
| 403 | 5103 / 5104 | 账户被禁用或暂停 | 联系能力方 |
| 403 | 5204 | 资源访问被拒绝 | 未开通该产品,或账号未绑定标签组 |
| 404 | 5000 | 服务配置异常 | 标签组被删等配置问题,联系能力方 |
| 409 | 4003 | 重复提交 | 换 client_request_id(同 id 不同请求体) |
| 400 | 1001 | 参数错误 | 按 message 改:条数、字数、标签数超限,标签不存在,组名不一致等 |
| 400 | 4102 | 必填缺失或互斥冲突 | 例如异步没带 client_request_id,或 tags 与 tag_group 同时传 |
| 400 | 4107 | 素材不可用 | URL 不合法、公网不可达、视频抽不出画面、域名解析失败。换素材,不要重试 |
| 413 | 1004 | 请求实体过大 | 缩短文本或换更小的素材 |
| 429 | 5705 | 请求过于频繁 | 退避重试(1 秒、3 秒、9 秒) |
| 429 | 9902 | 配额已超出 | 联系能力方提额 |
| 503 | 1502 | 服务暂不可用 | 上游或价格未就绪,退避重试 |
| 504 | 3600 | 上游处理超时 | 可重试一次(同一 client_request_id)。持续超时联系能力方 |
| 500 | 1500 | 服务器内部错误 | 带 meta.request_id 联系能力方 |
- 必须是公网可直接访问的 URL,且从调用开始到处理结束(最长 5 分钟)都要能访问。带鉴权、防盗链或内网地址不行。
- 视频支持 HLS(
.m3u8)和mp4。 - 图片支持 jpg、png、webp 等常见格式,单张建议不超过 10MB。
- 视频抽帧固定 8 帧。时长越长不代表越准;短视频同样适用。
按次计费。一次调用算一次,与素材数量、标签数量、抽帧数都无关。对外单价 2.00 元 / 次(试行价),以合同或报价单为准。计费单位是 request。
| 情况 | 是否计费 |
|---|---|
| 一次调用里放 100 条文本、20 张图、50 个标签 | 1 次 |
| 文本和视频一起传 | 1 次 |
视频异步(accepted 到 succeeded) | 1 次,只结算一次 |
同一 client_request_id 重放 | 不重复计费 |
0 命中(succeeded 且 tags: []) | 计费。上游确实跑完了 |
参数错误或素材不可用(1001、4102、4107、1004) | 不计费 |
无权限或余额不足(5204、9903) | 不计费 |
上游超时或失败(3600、1502、1500) | 不计费 |
结算时机:任务进入 succeeded 时结算一次,扣减账户余额。失败任务不产生扣费记录。用量与扣费可在后台「调用记录 / 账单」里按 request_id 对账,每条记录都会带当时的单价快照(unit_price)。
内部账号(internal)与包月账号按平台约定执行,不按上面单价逐次扣钱包。测试 Key(usage=test)只记调用不扣费,用于联调。
- 只使用标签名:请求传名字,响应回名字。标签的内部 id 不对外暴露。
- 标签名一旦上线不建议改。改名是破坏性变更,需要提前通知并同步调整。
- 账号默认绑定一个标签组。不传
tags时按组内全部标签打分。要新增或调整标签,联系能力方在后台维护,不需要发版。 - 单个请求候选标签上限 50 个。超过请拆成多次调用,每次算一次费用。
- 先用纯文本、3~5 个标签跑通鉴权与响应解析。
- 再试 0 命中(传高
threshold,如 0.9),确认前端能正确渲染「未命中」。 - 然后接图片,最后接视频(m3u8)。
- 视频链路务必测「轮询到
succeeded」和「轮询到failed」两条分支。 - 上线前确认:Key 只在服务端、超时不少于 350 秒、4xx 不自动重试、
client_request_id有唯一生成规则。
接口变更会提前通知。model_version 可能随上游升级变化,不要把它当固定值做逻辑判断。报障请提供 meta.request_id、model_version、发生时间、以及脱敏后的请求体。