<span id="检索任务内图片证据"></span>

# Retrieve task image evidence

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

Retrieve image evidence within the task.

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

<span id="调用前准备"></span>

## Before you call this API

Use injected service URLs, technical credentials, Workspace, and short-lived authorization only in the current task environment. Retain original authorization header values. An ordinary PAT cannot replace task identity or establish authorization. Examples use jq. See [Shared information](../../ai-studio/agents/message-connections/objects.md) for variables, objects, and states.

<span id="请求体"></span>

## Request body

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

```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} Parameters

Retain image, source, and location identities. Query images/retrieval hits are not automatically answer evidence. The API exposes only one query_visual_file_id, not model-internal query_visual or multi-image fields.

| Fields | Type | Required | Description |
| --- | --- | --- | --- |
| `request_id` | string | Yes | Unique ID for this operation, 1–256 bytes, without surrounding whitespace or an audit: prefix. Retain for replay of identical input. |
| `query_text` | string | Conditional | Text query; at least one of text/image query must be valid. |
| `query_visual_file_id` | string | Conditional | Query image file ID accessible to the current task. |
| `ranking_profile` | string | No | visual_object_first or visual_text_region_first. |
| `top_k` | integer | No | Nonnegative; omitted/0 uses 8. |

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

<span id="成功响应"></span>

## Successful response

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

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

:::::
:::::{tab-item} Fields

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | OK on success. |
| `msg` | string | Response explanation. |
| `data.call_id` | string | Corresponding original request_id. |
| `data.failed` | boolean | true indicates business failure; false may be omitted. |
| `data.output` | object | Current operation result. |
| `data.artifacts` | object (array of objects) | Original artifacts and evidence from the same task. |
| `data.metadata` | object | Operation metadata, returned when present. |
| `data.output.artifact_id` | string | Raw value returned by the current operation; retain according to common objects. |
| `data.output.results` | array | Image retrieval hits with original identities and locations. |
| `data.output.count` | integer | Returned image-hit count. |
| `data.output.mode` | string | Raw value returned by the current operation; retain according to common objects. |

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

<span id="错误响应"></span>

## Error response

Handle HTTP status, business results, and error fields separately. See [Errors and environments](../../ai-studio/agents/message-connections/objects.md#错误与环境). On source or version conflicts, read current state; do not automatically retry with a different identity, resource, or request ID.
