# Understand images
> Analyze one to eight images with stable input limits and per-image pricing.

Image understanding is available through authenticated MCP and REST as a
preview: the capability and price may change. 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`:

```json
{
  "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 in your account `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 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 accepted 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.