通用素材理解

通用素材理解（describe）是异步任务接口：提交图片（base64 / file_id，可混批）后立即返回任务 ID，云端视觉理解模型在后台逐图推理，轮询查询接口即可取回四维结果——内容描述（desc）、标签（tags）、质量分（mark）与可用性信号（usable_flags），直接回答「这张素材画面里是什么、质量如何、能不能用」。

与通用素材向量化互为姊妹能力：向量化是「找相似」的原料（传图文回向量，匹配你自己做）；理解是「知内容」的原料（传图回描述 / 标签 / 质量 / 可用性，取舍你自己做）。典型配合：先用向量检索召回候选，再用理解接口复核「像但不能用」的素材（水印、烧录字幕、黑边、模糊）。

💡 为什么是异步任务？ 视觉理解是模型推理，耗时随批次大小与模型负载波动。异步形态下提交成功即锁定任务：即使网络中断、客户端退出，任务照常完成，结果随时可凭任务 ID 取回——不会出现「等了半天连接断了、扣了费却拿不到结果」。

💡 批量索引检索请配合 gtrk CLI（内置提交与轮询，享内部工作流集成）。

提交理解任务

基本信息

项目	值
请求方法	`POST`
请求路径	`/task/material_describe`
Content-Type	`application/json`
鉴权方式	`Authorization` 请求头（直接传 API Key）
返回方式	异步任务（立即返回 `task_id`，轮询查询接口取结果）
计费	1 积分/张（提交时预扣，任务完成结算；失败自动全额退款）

请求参数（Body）

参数名	类型	必填	默认值	说明
`input`	`array`	是	—	混批输入数组，每项为 `{"image": "<base64>"}` 或 `{"file_id": "<已上传文件id>"}`（二选一，互斥——多键或零键报参数错误）；本接口仅收图像，`{"text": "..."}` 项将被拒绝并明示。任务结果按 `index` 与入参逐项对位。单请求上限 32 张图（`image` 与 `file_id` 形态合并计数），超限整单拒绝、明示上限，不做部分处理

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

字段	类型	说明
`image`	`string`	图片文件字节的 base64（兼容 data URI 形态），解码后单张 ≤ 1MB
`file_id`	`string`	已通过文件上传入库的图片文件 ID，免二次 base64 回传。须为本人上传且为图片类型（jpg / jpeg / png / bmp / webp）：不存在或非本人报 `6004`（同码，不泄露存在性），非图片类型报 `6014`。单图 ≤ 10MB（读盘无传输成本，与 `image` 形态的 1MB 分开限制），与 embed 接口同口径

请求示例

curl -X POST https://api.ai-mcn.tv:10000/task/material_describe \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": [
      {"image": "iVBORw0KGgoAAAANSUhEUgAA..."},
      {"file_id": "1954167xxxxxxxxxxxx"}
    ]
  }'

提交成功响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "1018322xxxxxxxxxxxx",
    "task_type": "material_describe",
    "status": "queued",
    "created_at": "2026-08-12 21:30:00"
  }
}

参数名	类型	说明
`task_id`	`string`	任务 ID（字符串形态，超出 JS 安全整数范围请勿转数字），凭它轮询结果
`status`	`string`	初始状态 `queued`（已排队）

查询任务结果

基本信息

项目	值
请求方法	`GET`
请求路径	`/task/material_describe/{task_id}`
鉴权方式	`Authorization` 请求头（直接传 API Key，仅可查本人任务）

轮询建议：间隔 5 秒左右；状态到达 completed / failed / cancelled 即终态。单张任务通常十余秒完成，满批 32 张约 1-3 分钟（受模型负载影响）。

响应示例（任务完成）

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "1018322xxxxxxxxxxxx",
    "status": "completed",
    "progress": 100,
    "output_result": {
      "data": [
        {
          "index": 0,
          "desc": "城市夜景航拍，镜头缓慢推进，主干道车流光轨与两侧高层建筑灯光形成纵深，整体色调偏冷。",
          "tags": ["城市", "夜景", "航拍", "车流"],
          "mark": 86,
          "usable_flags": {
            "watermark": false,
            "text_overlay": false,
            "black_border": false,
            "blurry": false
          }
        },
        {
          "index": 1,
          "desc": "室内人物访谈中景，画面右下角有平台水印，底部有烧录字幕。",
          "tags": ["人物", "访谈", "室内"],
          "mark": 42,
          "usable_flags": {
            "watermark": true,
            "text_overlay": true,
            "black_border": false,
            "blurry": false
          }
        }
      ],
      "usage": {"images": 2, "total": 2}
    }
  }
}

响应字段

参数名	类型	说明
`status`	`string`	任务状态：`queued`（排队）/ `processing`（处理中）/ `completed`（完成）/ `failed`（失败，已自动退款）/ `cancelled`（已取消，已自动退款）
`progress`	`integer`	处理进度百分比（逐图推进）
`output_result`	`object`	`completed` 时为理解结果（下表）；`failed` 时为错误信息
`output_result.data`	`array`	逐项对位的理解结果数组
`output_result.data[].index`	`integer`	对应提交 `input` 下标
`output_result.data[].desc`	`string`	画面内容描述，简体中文，≤ 200 字
`output_result.data[].tags`	`array`	3-8 个检索向属性标签（自由文本）
`output_result.data[].mark`	`number`	画面质量 / 审美分，0-100 百分制（至多两位小数），越高越好
`output_result.data[].usable_flags`	`object`	可用性信号（四维布尔），详见下表
`output_result.usage.images`	`integer`	本次图像张数
`output_result.usage.total`	`integer`	合计条数

usable_flags 对象

字段	类型	说明
`watermark`	`boolean`	是否可见水印 / 台标 / 品牌角标
`text_overlay`	`boolean`	是否可见烧录字幕 / 叠加文字
`black_border`	`boolean`	是否可见上下 / 左右黑边
`blurry`	`boolean`	是否明显失焦 / 运动模糊

ℹ️ 说明：usable_flags 定位为供你复核的信号，不是硬门禁——建议结合 desc 一并判断；模型解析缺失某维度时按 false 兜底（宁放行勿误杀）。

ℹ️ 隐私说明：帧图经同合云基础设施临时中转（供理解模型访问），即传即弃——任务完成即清理，不留存。

⚠️ 注意：本接口不收视频：视频素材请先在本地抽帧，再将帧图传入。

计费口径

1 积分/张，提交预扣、完成结算：提交时预扣 = 图像张数 × 1 积分四舍五入取整，每任务最低收 1 积分。image（base64）与 file_id 两种形态的图像同等按张计费。
失败全额退款：任务失败（含任一图理解失败——不做部分成功出账）或被取消时，预扣积分自动全额退回，不留半账。
同合云内部成员豁免：gc_member_type 为 internal 的账户（见用户管理）零计费。
余额 / 额度不足时提交直接失败（HTTP 402），前置拒绝、不建任务，不产生半账。

错误码

提交接口（任务未创建，不扣费）：

错误码	HTTP 状态码	说明	解决方案
`6013`	400	必填参数缺失（`input`）	补齐必填参数
`6016`	400	业务参数非法（`input` 项含 `text` 形态、非二选一互斥形态等——本接口仅收图像）	按参数说明修正
`6004`	404	`file_id` 文件不存在或不属于当前用户（两情形同码，不泄露存在性）	确认 `file_id` 来自本账号的上传记录且未过期
`6014`	400	`file_id` 指向的文件不是图片类型	仅可引用图片文件（jpg / jpeg / png / bmp / webp）
`6030`	400	单请求输入超上限（图 > 32 张），整单拒绝	分批提交
`6031`	413	单张图片超过大小上限：`image` 形态解码后 > 1MB，或 `file_id` 形态文件 > 10MB（两形态分开限制，报错文案会指明形态）	压缩 / 缩放后重传
`6032`	429	按 key 频率限流（30 请求/分钟，值可配置）	降低提交频率后重试
`6201`	402	余额 / 配额不足（前置拒绝，不建任务不扣费）	购买配额包或充值
`6502`	401	鉴权失败	检查 `Authorization` 请求头

任务执行失败（不走 HTTP 错误码）：上游模型不可用 / 超时等执行期故障会先自动重试；重试耗尽后任务进入 failed 状态、预扣积分自动全额退回，output_result 记录错误信息——轮询到 failed 后按需重新提交即可。

使用限制

单请求上限 32 张图（image 与 file_id 形态合并计数）；按 key 30 请求/分钟（值均可配置）。
单图大小两形态分开限制：image（base64）形态解码后 ≤ 1MB；file_id 形态 ≤ 10MB（引用已上传文件，无传输成本，故上限更宽）。
file_id 仅可引用本人上传、图片类型（jpg / jpeg / png / bmp / webp）且未过期的文件。
仅收图像：input 不接受 text 形态；视频素材请先在本地抽帧后传图。
异步任务：提交后轮询取结果（建议间隔 5 秒）；单张任务通常十余秒，满批 32 张约 1-3 分钟。

通用素材理解

提交理解任务

基本信息

请求参数（Body）

请求示例

提交成功响应示例

查询任务结果

基本信息

响应示例（任务完成）

响应字段

usable_flags 对象

计费口径

错误码

使用限制

下一步