Understand images

Image understanding is available through authenticated MCP and REST as a Preview capability. Submit one to eight ordered images and a prompt; Beatra returns a durable asynchronous task.

MCP

Call beatra.images.understand with one stable client_request_id:

{
  "client_request_id": "understand-products-01",
  "model": "auto",
  "prompt": "Compare the products and list the important differences.",
  "images": [
    { "type": "url", "url": "https://example.com/front.jpg" },
    { "type": "artifact", "artifact_id": "artifact_back" }
  ],
  "detail": "default",
  "response_format": "text"
}

Use beatra.models.list with capability: "image_to_text" when current model, limit, or price facts matter. Submit the finalized arguments once, then poll the returned task_id with beatra.tasks.get. On success, the answer is in both structuredContent.task.output.text and the MCP text content.

For a local image, call beatra.assets.upload with the exact MIME type and byte length, perform the returned HTTPS PUT with the raw bytes, and pass the returned artifact_id as an artifact input. The uploaded source remains in the account asset library.

REST

Send the same understanding fields, without client_request_id, to POST /v1/images/responses and provide a stable Idempotency-Key header. Poll GET /v1/tasks/{task_id} until terminal.

Each input may be a tenant-owned artifact, an external HTTPS url, or a base64 data_uri. External and inline inputs are validated, stored in the account's uploaded-material library, and passed to the model from Beatra's CDN.

Contract

• prompt is required and must contain non-whitespace text.
• images is required and accepts 1–8 ordered images.
• Each decoded image is limited to 10 MiB.
• detail accepts default, low, or high and defaults to default. It does not change the customer price.
• thinking is not a public field. MiniMax M3 uses adaptive thinking internally.
• The selectable model is MiniMax-M3; use auto unless a specific model is required. Live availability remains authoritative.

Billing

Successful requests cost 5 credits per admitted image. A request with eight images therefore costs 40 credits. Provider token usage remains internal and does not change this endpoint's customer charge. Failed tasks are not charged.

Uploaded source materials remain available in the account asset library; temporary server files used during ingestion are deleted after processing.