> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Vision

> 了解如何運用視覺能力理解影像。

## 能力概覽

Vision 能力支援模型同時理解影像與文字,可依據影像內容進行分析、描述、判斷與問答。開發者可以在單次請求中向模型傳送一張或多張影像,並搭配自然語言指令,完成多模態理解任務。典型能力包含:

* 影像內容描述(物件、場景、動作)
* 影像問答(針對影像提問)
* 多張影像的比較分析與綜合
* 影像 + 文字的聯合推理

## 快速開始

```python theme={null}
from openai import OpenAI

client = OpenAI(
  api_key="<AIHUBMIX_API_KEY>",
  base_url="https://aihubmix.com/v1"
)

response = client.chat.completions.create(
  model="gpt-4o",
  messages=[
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What’s in this image?"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg",
            "detail": "auto"
          },
        },
      ],
    }
  ],
  max_tokens=300,
)

print(response.choices[0])
```

## 支援的輸入格式

影像可以透過兩種主要方式提供給模型:傳遞影像連結,或直接在請求中包含 base64 編碼的影像。影像可以包含在 `user`、`system` 與 `assistant` 訊息中。目前不支援在第一個 `system` 訊息中傳入影像。

### 影像 URL 輸入(推薦)

直接傳入公開網際網路可存取的影像 URL,適合線上業務情境。

```json theme={null}
{
  "type": "image_url",
  "image_url": {
    "url": "https://example.com/demo.jpg"
  }
}
```

<Tip>
  **注意事項:**

  * URL 必須可由模型存取。
  * 影像格式應為 PNG / JPEG / WEBP / non-GIF。
  * 單張影像大小不得超過 20MB。
</Tip>

### Base64 編碼影像輸入

適合本機檔案或私有影像情境。

**流程說明:**

1. 在本機讀取影像檔案。
2. 將其轉換為 base64 字串。
3. 在請求中作為影像內容傳入。

```json theme={null}
{
  "type": "image_url",
  "image_url": {
    "url": "data:image/png;base64,<BASE64_DATA>"
  }
}
```

## 訊息結構範例

影像通常會搭配文字指令一起傳送,以明確模型的理解目標。

```json theme={null}
{
  "role": "user",
  "content": [
    { "type": "text", "text": "Please describe the main content of this image" },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/photo.jpg"
      }
    }
  ]
}
```

## 多影像輸入

可在單次請求中提交多張影像,讓模型整合所有影像的理解。

```json theme={null}
{
  "role": "user",
  "content": [
    { "type": "text", "text": "Compare the differences between these two images" },
    { "type": "image_url", "image_url": { "url": "https://example.com/a.jpg" } },
    { "type": "image_url", "image_url": { "url": "https://example.com/b.jpg" } }
  ]
}
```

***

## 影像清晰度控制(detail 參數)

可以使用 `detail` 參數控制模型在處理影像時所採用的細節層級:

| 參數值    | 說明                   |
| :----- | :------------------- |
| `low`  | 低解析度,速度快,token 消耗少   |
| `high` | 高解析度,細節更豐富,token 消耗高 |
| `auto` | 自動選擇(預設)             |

```json theme={null}
{
  "image_url": {
    "url": "https://example.com/photo.jpg",
    "detail": "high"
  }
}
```

**建議策略:**

* 內容理解 / 場景判斷:`auto` 或 `low`
* 需要細節觀察時(文字、特定部位):`high`

***

## 計費與 Token 說明

視覺輸入會消耗額外的 token,在成本評估時應一併考量:

* `low` 模式:每張影像消耗固定的 **85 tokens**
* `high` 模式:token 消耗會依影像大小與解析度增加

**建議:**

* 預設使用 `auto`
* 在批次或高並行情境中,避免不必要的 `high`

## 使用建議

* 一律提供清晰的文字指令;不要單獨傳送影像。
* 控制影像數量與解析度以避免不必要的成本。
* 對於關鍵業務結果,進行二次驗證。
* 將視覺理解作為輔助能力,不要作為唯一判斷依據。

***

最後更新：2026-06-01