多模态内容检索接口文档

给文本、图片或视频按标签打分,返回分数和判定理由。文本和图片同步返回;视频或带回调时异步,完成后查询或回调。按次计费。

给一段文本、一张或多张图片、或一个视频,返回它命中了哪些标签,以及每个标签的分数和判定理由。适用产品:retrieval(多模态内容检索·全量打分),按次计费。

标签由能力方维护(例如「古装」「都市」「爱情」「自然风景」)。调用方只传标签名,不传任何内部 id。每个客户账号绑定一个标签组;不传 tags 时,按绑定组里的全部标签打分。返回的是结构化结果,没有图片或视频产物。

方法与路径说明
POST /api/retrieval/score发起检索打分。文本、图片同步返回;视频或带回调时异步
GET /api/tasks/{request_id}查询异步任务
环境根地址
测试https://test-star-api.aiaibase.com
正式https://star-api.aiaibase.com

路径接在根地址后面。例如正式环境发起检索:

text
POST https://star-api.aiaibase.com/api/retrieval/score

请求体为 JSON,Content-Type: application/json,字符集 UTF-8。认证只使用请求头:

text
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 起)。

请求示例

同步,指定标签:

bash
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,使用账号绑定组里的全部标签:

bash
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
  }'

异步,视频:

bash
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"
  }'

文本和图片在同一次请求里返回打分结果。

json
{
  "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"
  }
}
字段说明
statussucceeded 成功;failed 失败(看 error)
tags[]命中的标签,按分数从高到低
tags[].tag_name标签名,就是请求里传的名字,或绑定组里的名字
tags[].score0~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):

json
{
  "success": true,
  "data": {
    "status": "succeeded",
    "tags": [],
    "threshold": 0.8,
    "stats": {
      "returned_count": 0
    }
  }
}

带 video 或 notice_url 提交后立即返回受理结果。此时还没有打分结论。request_id 在 meta.request_id,data 里没有。

json
{
  "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 查询,鉴权头与提交接口相同:

text
GET /api/tasks/{request_id}
Authorization: Bearer {API Key}

返回结构与同步成功相同。

data.status含义后续动作
accepted / pending / running排队或处理中每 3~10 秒轮询,建议上限 6 分钟
succeeded完成(含 tags: [])取 tags 展示
failed失败看 error.code,按错误码处理

前端处理:

  1. 后端拼 POST /api/retrieval/score。
  2. 同步返回(文本、图片):直接拿到 tags。
  3. 异步返回(视频或回调):拿 meta.request_id,进入处理中。
  4. 每 3~10 秒调 GET /api/tasks/{request_id}。succeeded 后渲染 tags;tags: [] 渲染为「未命中任何标签」。
  5. 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。

失败时返回:

json
{
  "success": false,
  "message": "...",
  "error": {
    "code": 1001,
    "message": "..."
  },
  "meta": {}
}

message 给开发者看,可直接打日志。给最终用户展示时请换成人话,例如 4107 展示为「素材读取失败,请换一个链接」。

HTTPcode含义处理
4015003认证信息无效检查 Key 是否被环境用错
4015301令牌已过期换新 Key
4015304令牌已被撤销联系能力方
4029903余额不足充值后再调。本次不计费
4035103 / 5104账户被禁用或暂停联系能力方
4035204资源访问被拒绝未开通该产品,或账号未绑定标签组
4045000服务配置异常标签组被删等配置问题,联系能力方
4094003重复提交换 client_request_id(同 id 不同请求体)
4001001参数错误按 message 改:条数、字数、标签数超限,标签不存在,组名不一致等
4004102必填缺失或互斥冲突例如异步没带 client_request_id,或 tags 与 tag_group 同时传
4004107素材不可用URL 不合法、公网不可达、视频抽不出画面、域名解析失败。换素材,不要重试
4131004请求实体过大缩短文本或换更小的素材
4295705请求过于频繁退避重试(1 秒、3 秒、9 秒)
4299902配额已超出联系能力方提额
5031502服务暂不可用上游或价格未就绪,退避重试
5043600上游处理超时可重试一次(同一 client_request_id)。持续超时联系能力方
5001500服务器内部错误带 meta.request_id 联系能力方

  1. 必须是公网可直接访问的 URL,且从调用开始到处理结束(最长 5 分钟)都要能访问。带鉴权、防盗链或内网地址不行。
  2. 视频支持 HLS(.m3u8)和mp4。
  3. 图片支持 jpg、png、webp 等常见格式,单张建议不超过 10MB。
  4. 视频抽帧固定 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 个。超过请拆成多次调用,每次算一次费用。

  1. 先用纯文本、3~5 个标签跑通鉴权与响应解析。
  2. 再试 0 命中(传高 threshold,如 0.9),确认前端能正确渲染「未命中」。
  3. 然后接图片,最后接视频(m3u8)。
  4. 视频链路务必测「轮询到 succeeded」和「轮询到 failed」两条分支。
  5. 上线前确认:Key 只在服务端、超时不少于 350 秒、4xx 不自动重试、client_request_id 有唯一生成规则。

接口变更会提前通知。model_version 可能随上游升级变化,不要把它当固定值做逻辑判断。报障请提供 meta.request_id、model_version、发生时间、以及脱敏后的请求体。