通用素材向量化

通用素材向量化（embed）是同步接口：传入文本 / 图片（base64，可混批），直接返回满 1024 维的归一化向量，与云端素材矩阵同一语义空间——向量可跨图文互搜，匹配计算在你本地完成，云端只负责出向量。

典型用途：为自有素材建立向量索引、做语义去重 / 聚类，或将查询文本向量化后与本地索引比对完成检索。与 视频素材检索（智能剪辑） 互为姊妹能力：那边传关键字、云端直接回匹配好的素材；这边传图文、云端只回向量，匹配由你自己做。

💡 批量索引场景请使用 gtrk CLI（享会话计量，按实际用量精确结算）。

向量化接口

基本信息

项目	值
请求方法	POST
请求路径	/task/material_embed
Content-Type	application/json
鉴权方式	Authorization 请求头（直接传 API Key）
返回方式	同步返回向量（非异步任务）
计费	图像 0.1 积分/张（按请求结算，四舍五入、有图最低 1 积分）；文本免费

请求参数（Body）

参数名	类型	必填	默认值	说明
input	array	是	—	混批输入数组，每项为 {"text": "..."}、{"image": "<base64>"} 或 {"file_id": "<已上传文件id>"}（三选一，互斥——多键或零键报参数错误）；响应按 index 与入参逐项对位。单请求上限 16 张图（image 与 file_id 形态合并计数）或 64 条文本，超限整单拒绝、明示上限，不做部分处理
normalized	boolean	否	true	仅支持 true（显式传 false 将被拒绝）；响应恒为归一化向量
task	string	否	—	文本侧任务前缀，与云端检索同口径（检索查询文本建议传 retrieval.query）；图像侧忽略该参数；长度 ≤ 64

input[] 元素（text / image / file_id 三选一，互斥）

字段	类型	说明
text	string	待向量化文本（非空字符串）
image	string	图片文件字节的 base64（兼容 data URI 形态），解码后单张 ≤ 1MB；建议先缩放到 512px 再传
file_id	string	已通过文件上传入库的图片文件 ID，免二次 base64 回传。须为本人上传且为图片类型（jpg / jpeg / png / bmp / webp）：不存在或非本人报 6004（同码，不泄露存在性），非图片类型报 6014。单图 ≤ 10MB（读盘无传输成本，与 image 形态的 1MB 分开限制）；向量化结果与 base64 传同一张图完全一致

请求示例

curl -X POST https://api.ai-mcn.tv:10000/task/material_embed \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": [
      {"text": "城市夜景航拍"},
      {"image": "iVBORw0KGgoAAAANSUhEUgAA..."},
      {"file_id": "1954167xxxxxxxxxxxx"}
    ],
    "normalized": true
  }'

成功响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "data": [
      {"index": 0, "embedding": [0.0123, -0.0456, 0.0789]},
      {"index": 1, "embedding": [0.0234, 0.0567, -0.0891]},
      {"index": 2, "embedding": [-0.0142, 0.0378, 0.0655]}
    ],
    "usage": {"texts": 1, "images": 2, "total": 3}
  }
}

ℹ️ 说明：示例中 embedding 为截断展示，实际为满 1024 维 float 数组；file_id 形态的图片同样计入 usage.images。

响应字段

参数名	类型	说明
data	array	逐项对位的向量数组
data[].index	integer	对应 input 下标
data[].embedding	array	1024 维归一化 float 向量，与云端素材矩阵同语义空间
usage.texts	integer	本次文本条数
usage.images	integer	本次图像张数（按成功交付计费）
usage.total	integer	合计条数

⚠️ 注意：模型懒加载 + 空闲逐出，逐出后的首个请求可能慢（分钟级冷启动），客户端超时请设 ≥ 180 秒；连续请求场景仅首批慢。

计费口径

• 图像 0.1 积分/张，按请求结算：每次请求应收 = 图像张数 × 0.1 积分四舍五入取整；请求含图像时最低收 1 积分。按成功交付的图像张数计费，失败请求不计费。image（base64）与 file_id 两种形态的图像同等按张计费。
• 文本免费：纯文本请求零积分。
• 同合云内部成员豁免：gc_member_type 为 internal 的账户（见 用户管理）零计费。
• 余额 / 额度不足时请求直接失败（HTTP 402），不产生半账。
• 批量索引会产生大量小额请求，逐请求四舍五入会放大计费误差——此场景请改用 gtrk CLI（享会话计量，按实际用量精确结算）。

错误码

错误码	HTTP 状态码	说明	解决方案
6013	400	必填参数缺失（input）	补齐必填参数
6016	400	业务参数非法（input 项非三选一互斥形态、normalized 显式传 false、task 超长等）	按参数说明修正
6004	404	file_id 文件不存在或不属于当前用户（两情形同码，不泄露存在性）	确认 file_id 来自本账号的上传记录且未过期
6014	400	file_id 指向的文件不是图片类型	仅可引用图片文件（jpg / jpeg / png / bmp / webp）
6030	400	单请求输入超上限（图 > 16 张或文本 > 64 条），整单拒绝	分批请求
6031	413	单张图片超过大小上限：image 形态解码后 > 1MB，或 file_id 形态文件 > 10MB（两形态分开限制，报错文案会指明形态）	压缩 / 缩放后重传（建议 512px）
6032	429	按 key 频率限流（60 请求/分钟，值可配置）	降低请求频率后重试
6201	402	配额不足	购买配额包或充值
6202	402	余额不足	前往仪表盘充值
6502	401	鉴权失败	检查 Authorization 请求头
6401	500	上游模型服务不可用	稍后重试
6402	500	上游模型服务超时（含冷启动超限）	稍后重试；客户端超时设 ≥ 180 秒

使用限制

• 单请求上限 16 张图（image 与 file_id 形态合并计数）或 64 条文本；按 key 60 请求/分钟（值均可配置）。
• 单图大小两形态分开限制：image（base64）形态解码后 ≤ 1MB；file_id 形态 ≤ 10MB（引用已上传文件，无传输成本，故上限更宽）。
• file_id 仅可引用本人上传、图片类型（jpg / jpeg / png / bmp / webp）且未过期的文件。
• normalized 仅支持 true，响应恒为归一化向量。
• 模型懒加载：空闲逐出后的首个请求可能出现分钟级冷启动，客户端超时请设 ≥ 180 秒。

下一步

• 视频素材检索（智能剪辑）
• 通用素材检索
• 用户管理