# 检索任务内图片证据

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

检索任务内图片证据。

```text
POST https://api.moi.matrixorigin.cn/v5/semantic-models/runtime/search-images
```

## 调用前准备

仅在当前任务执行环境使用注入的服务地址、技术凭据、工作区和短期授权；保留授权头原值。普通 PAT 不能替代任务身份或建立授权。示例使用 jq；变量、对象与状态见[公共说明](../../ai-studio/agents/message-connections/objects.md)。

## 请求体

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

```bash
curl -X POST "${MOI_ENDPOINT%/}/semantic-models/runtime/search-images" \
  -H "X-API-Key: $MOI_API_KEY" \
  -H "X-Workspace-ID: $MOI_WORKSPACE_ID" \
  -H "X-MOI-Runtime-Authorization: $MOI_RUNTIME_AUTHORIZATION" \
  -H 'Content-Type: application/json' \
  --data-binary "$(jq -n --arg REQUEST_ID "$REQUEST_ID" --arg KNOWLEDGE_QUERY "$KNOWLEDGE_QUERY" '
{
  "request_id": $REQUEST_ID,
  "query_text": $KNOWLEDGE_QUERY,
  "top_k": 3
}
')"
```

:::::
:::::{tab-item} 参数说明

保留图片、来源与定位；不把查询图或检索命中直接当成回答依据。API 只暴露单个 query_visual_file_id，不套用模型内部的 query_visual 或多图字段。

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `request_id` | string | 是 | 本次操作的唯一 ID，1–256 字节，无首尾空白，不以 audit: 开头；重放同一输入时保留原值。 |
| `query_text` | string | 条件必填 | 文本查询；与图片查询至少一项有效。 |
| `query_visual_file_id` | string | 条件必填 | 当前任务可访问的查询图片文件 ID。 |
| `ranking_profile` | string | 否 | visual_object_first 或 visual_text_region_first。 |
| `top_k` | integer | 否 | 非负；省略/0 使用 8。 |

:::::
::::::
:::::::

## 成功响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "call_id": "request_example",
    "output": {
      "artifact_id": "visual_search_example",
      "results": [],
      "count": 0,
      "mode": "text"
    }
  }
}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 OK。 |
| `msg` | string | 响应说明。 |
| `data.call_id` | string | 对应原 request_id。 |
| `data.failed` | boolean | true 表示业务失败；false 时可省略。 |
| `data.output` | object | 当前操作结果。 |
| `data.artifacts` | object（对象数组） | 同一任务的原始产物与证据。 |
| `data.metadata` | object | 操作元数据，存在时返回。 |
| `data.output.artifact_id` | string | 当前操作返回的原始值，按公共对象说明保留。 |
| `data.output.results` | array | 图片检索的命中结果，保留原身份与定位。 |
| `data.output.count` | integer | 返回的图片命中数。 |
| `data.output.mode` | string | 当前操作返回的原始值，按公共对象说明保留。 |

:::::
::::::
:::::::

## 错误响应

按 HTTP 状态、业务结果和错误字段处理，见[错误与环境](../../ai-studio/agents/message-connections/objects.md#错误与环境)。来源与版本冲突时读取当前状态，不替换身份、资源或请求 ID 自动重试。
