# 画像理解
> 1〜8 枚の画像を、固定された入力上限と画像単位の料金で解析します。

画像理解は、認証済み MCP と REST の両方で利用できるプレビュー機能です。機能と価格は変わることがあります。
1〜8 枚の順序付き画像とプロンプトを送信すると、永続的な非同期タスクが返ります。

## MCP

1 回の論理リクエストに対して安定した `client_request_id` を作り、
`beatra.images.understand` を呼び出します。

```json
{
  "client_request_id": "understand-products-01",
  "model": "auto",
  "prompt": "商品を比較し、重要な違いを挙げてください。",
  "images": [
    { "type": "url", "url": "https://example.com/front.jpg" },
    { "type": "artifact", "artifact_id": "artifact_back" }
  ],
  "detail": "default",
  "response_format": "text"
}
```

現在のモデル、上限、料金を確認するときは、`beatra.models.list` に
`capability: "image_to_text"` を渡します。確定した引数は一度だけ送信し、
返された `task_id` を `beatra.tasks.get` で終端状態までポーリングします。
成功時の回答は `structuredContent.task.output.text` と MCP テキストの両方にあります。

ローカル画像は、正確な MIME タイプとバイト数で `beatra.assets.upload` を呼び、
返された HTTPS `PUT` を生バイトで実行し、レスポンスの `artifact_id` を
`artifact` 入力として使用します。元素材はアカウントの素材ライブラリに残ります。

## REST

同じ理解フィールドから `client_request_id` を除き、安定した
`Idempotency-Key` ヘッダーとともに `POST /v1/images/responses` へ送信します。
`GET /v1/tasks/{task_id}` を終端状態までポーリングします。

入力にはあなたのアカウントにある `artifact`、外部 HTTPS `url`、base64 `data_uri`
を使用できます。外部・インライン素材は検証後、アカウントの素材ライブラリに
保存され、Beatra CDN からモデルへ渡されます。

## 契約と料金

- `prompt` は必須で、空白以外のテキストを含む必要があります。
- `images` は必須で 1〜8 枚、1 枚あたり最大 10 MiB です。
- `detail` は `default`、`low`、`high`。既定値は `default` で料金に影響しません。
- `thinking` は公開しません。MiniMax M3 は内部で adaptive thinking を使います。
- モデルは `MiniMax-M3` です。通常は `auto` を使用します。
- 成功時は**受理画像 1 枚あたり 5 クレジット**。8 枚なら 40 クレジットです。
  失敗タスクは課金されません。

入力素材は素材ライブラリに残り、取り込み時のサーバー一時ファイルは処理後に
削除されます。