Retrieve task image evidence

Retrieve image evidence within the task.

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

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 for variables, objects, and states.

Request body

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

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.

Successful response

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

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.

Error response

Handle HTTP status, business results, and error fields separately. See Errors and environments. On source or version conflicts, read current state; do not automatically retry with a different identity, resource, or request ID.

Last updated on