影像理解（識圖）API

API易提供強大的影像理解能力，支援使用多種先進的 AI 模型對影像進行深度分析和理解。通過統一的 OpenAI API 格式，您可以輕鬆實現影像識別、場景描述、OCR 文字識別等功能。

🔍 智慧視覺分析
支援物件識別、場景理解、文字提取、情感分析等多種視覺任務，讓 AI 真正”看懂”圖片。

🌟 核心特性

🎯 多模型支援：Gemini 3 系列、GPT-5 系列、Claude 4 系列等頂級多模態模型
📸 靈活輸入：支援 URL 連結和 Base64 編碼圖片
🌏 中文最佳化：完美支援中文場景理解和文字識別
⚡ 快速響應：高效能推理，秒級返回結果
💰 成本可控：多種模型選擇，滿足不同預算需求

📋 支援的視覺模型

以下為當前主流的多模態模型推薦，模型 ID 可能隨版本更新，請以控制台為準。

模型名稱	模型 ID	特點	推薦場景
Gemini 3.1 Pro Preview ⭐	`gemini-3.1-pro-preview`	最強多模態推理，細節豐富	複雜影像/場景分析
Gemini 3.5 Flash 🔥	`gemini-3.5-flash`	速度快、價格低，價效比之王	即時識圖、批次處理
GPT-5.5 ⭐	`gpt-5.5`	綜合視覺理解強，穩定可靠	通用影像理解
Claude Opus 4.7	`claude-opus-4-7`	理解深入，描述精準	專業圖文分析
Claude Sonnet 4.6	`claude-sonnet-4-6`	效能媲美 Opus，價效比高	高性價比識圖
GPT-4o	`gpt-4o`	經典多模態，成熟穩定	通用場景
Gemini 2.5 Flash	`gemini-2.5-flash`	超快超便宜，正式版	大批次簡單識圖

絕大多數對話模型現已支援多模態識圖：上表僅為常用推薦，並非全部。GPT-5 系列、Gemini 3 系列、Claude 4 系列、Grok 4、Qwen、GLM、Kimi 等主流模型大多已支援影像輸入。

📚 完整模型清單與特點對比：當下熱門模型（保持更新）
🔗 即時模型列表與價格：API易控制台定價頁面（以控制台顯示是否支援視覺為準）

🚀 快速開始

1. 基礎示例 - 圖片 URL

import requests

url = "https://api.apiyi.com/v1/chat/completions"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

payload = {
    "model": "gpt-5.5",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "請詳細描述這張圖片的內容"
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/image.jpg"
                    }
                }
            ]
        }
    ]
}

response = requests.post(url, headers=headers, json=payload)
result = response.json()
print(result['choices'][0]['message']['content'])

2. 本地圖片示例 - Base64 編碼

import base64
import requests

def image_to_base64(image_path):
    """將本地圖片轉換為 base64 編碼"""
    with open(image_path, "rb") as image_file:
        return base64.b64encode(image_file.read()).decode('utf-8')

# 讀取本地圖片
base64_image = image_to_base64("path/to/your/image.jpg")

url = "https://api.apiyi.com/v1/chat/completions"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

payload = {
    "model": "gemini-3.1-pro-preview",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "分析這張圖片中的所有文字內容"
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:image/jpeg;base64,{base64_image}"
                    }
                }
            ]
        }
    ]
}

response = requests.post(url, headers=headers, json=payload)
print(response.json()['choices'][0]['message']['content'])

3. 高階示例 - 多圖對比分析

import requests

url = "https://api.apiyi.com/v1/chat/completions"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

payload = {
    "model": "gemini-3.1-pro-preview",
    "messages": [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "請對比這兩張圖片的差異："},
                {
                    "type": "image_url",
                    "image_url": {"url": "https://example.com/image1.jpg"}
                },
                {
                    "type": "image_url", 
                    "image_url": {"url": "https://example.com/image2.jpg"}
                }
            ]
        }
    ],
    "max_tokens": 1000
}

response = requests.post(url, headers=headers, json=payload)
print(response.json()['choices'][0]['message']['content'])

4. cURL 示例（命令列）

圖片 URL 方式：

curl https://api.apiyi.com/v1/chat/completions \
  -H "Authorization: Bearer $APIYI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-pro-preview",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "請詳細描述這張圖片的內容" },
          { "type": "image_url", "image_url": { "url": "https://example.com/image.jpg" } }
        ]
      }
    ]
  }'

本地圖片 Base64 方式（先把圖片編碼成 Base64 再拼進請求體）：

# 1. 將本地圖片轉為 base64（macOS / Linux）
BASE64_IMAGE=$(base64 -i path/to/your/image.jpg | tr -d '\n')

# 2. 通過 data URI 傳入圖片內容
curl https://api.apiyi.com/v1/chat/completions \
  -H "Authorization: Bearer $APIYI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "分析這張圖片中的所有文字內容" },
          { "type": "image_url", "image_url": { "url": "data:image/jpeg;base64,'"$BASE64_IMAGE"'" } }
        ]
      }
    ]
  }'

推薦優先使用 Base64 方式上傳圖片：圖片 URL 方式需要伺服器先即時下載該圖片，若圖床響應慢或有訪問限制，就會下載失敗；Base64 把圖片資料直接放進請求體，不依賴任何外部下載，穩定性更高。兩種方式官方均支援，Base64 體積約為原圖的 1.33 倍，大圖建議先適度壓縮再編碼。

5. 常見錯誤：圖片 URL 下載超時

使用圖片 URL 方式時，如果收到如下錯誤：

{
  "error": {
    "message": "Timeout while downloading ip:port",
    "type": "invalid_request_error",
    "code": "invalid_image_url"
  }
}

這表示伺服器在拉取該圖片 URL 時下載超時，與模型、金鑰、額度均無關。常見原因：

圖床 / 源站響應慢，或對部分地區網路訪問不友好
圖片體積過大，下載耗時超出限制
URL 設有防盜鏈、需要登入或非公開直鏈

解決方法：

✅ 改用 Base64（data URI）方式上傳（推薦，見上方示例 2）——圖片資料隨請求體直接提交，徹底繞開下載環節，最穩定
更換為響應更快、可公開訪問的圖片直鏈
壓縮圖片後重試

6. 常見錯誤：invalid base64 data（URL 誤放進 Base64 欄位）

如果收到如下 400 錯誤（以 Claude 系模型為例，其它模型系列文案略有差異，關鍵特徵是 invalid base64 data）：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "...source.base64: invalid base64 data"
  },
  "request_id": "req_011CczN..."
}

通常是把圖片 URL 拼進了 data URI 的 Base64 資料位：

// ❌ 錯誤寫法：base64, 後面跟的是圖片連結，不是 Base64 編碼
"image_url": {
  "url": "data:image/jpeg;base64,https://example.com/generations/temp-xxx.jpg"
}

data:image/...;base64, 字首後面必須是圖片檔案本身的 Base64 編碼字串，而不是圖片連結。URL 方式和 Base64 方式是兩種互斥的傳參形式，不能混拼。常見誘因：程式碼裡統一走了 data URI 拼接邏輯，遇到 URL 圖片也直接拼了進去。 正確寫法對照：

// ✅ 圖片是網路 URL → 直接傳連結，不加任何字首
"image_url": {
  "url": "https://example.com/generations/temp-xxx.jpg"
}

// ✅ 圖片是本地檔案/二進位制 → 先 Base64 編碼，再拼 data URI（見上方示例 2）
"image_url": {
  "url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
}

自檢建議：傳送前判斷一下圖片來源——字串以 http 開頭就走 URL 方式，否則才做 Base64 編碼並拼 data URI。另外，合法的 Base64 字串不會包含 ://、? 等字元，若在 base64, 之後看到這些字元，基本可以斷定是把連結拼進去了。

7. 常見錯誤：宣告的圖片格式與實際格式不符（media type mismatch）

如果收到如下 400 錯誤（關鍵特徵是 The image was specified using the image/png media type, but the image appears to be a image/jpeg image）：

{
  "status_code": 400,
  "error": {
    "message": "InvokeModel: operation error Bedrock Runtime: InvokeModel, https response error StatusCode: 400, RequestID: e87a35ed-..., ValidationException: ...source.base64: The image was specified using the image/png media type, but the image appears to be a image/jpeg image"
  }
}

報錯解讀：這條錯誤來自上游模型服務的入參校驗（示例中的 Bedrock Runtime: InvokeModel, ValidationException 表示請求已到達 Claude 系模型的上游通道，在引數校驗階段被拒絕）。它的意思非常直白：

你在 data URI 裡宣告圖片是 PNG（data:image/png;base64,...）
但上游解碼 Base64 後檢查檔案頭（magic bytes），發現實際內容是 JPEG
宣告與實際不一致 → 400 拒絕。Base64 編碼本身沒有問題，問題出在字首裡的 media type 寫錯了

常見誘因：

按副檔名推斷 MIME 型別，但副檔名是假的——檔名叫 xxx.png，實際是別人改過後綴的 JPEG（下載工具、聊天軟體、截圖工具都可能幹這事）
程式碼裡寫死了 image/png（或寫死 image/jpeg），不管傳什麼圖都用同一個字首
圖片經過某些處理管道後格式變了，但檔名沒變

解決方法：不要相信副檔名，按檔案真實內容（檔案頭）判斷 MIME 型別再拼 data URI：

import base64

def image_to_data_uri(image_path):
    """按檔案頭識別真實格式，杜絕 media type 與內容不一致"""
    with open(image_path, "rb") as f:
        data = f.read()

    if data[:8] == b"\x89PNG\r\n\x1a\n":
        mime = "image/png"
    elif data[:3] == b"\xff\xd8\xff":
        mime = "image/jpeg"
    elif data[:6] in (b"GIF87a", b"GIF89a"):
        mime = "image/gif"
    elif data[:4] == b"RIFF" and data[8:12] == b"WEBP":
        mime = "image/webp"
    else:
        raise ValueError(f"無法識別的圖片格式: {image_path}")

    return f"data:{mime};base64,{base64.b64encode(data).decode('utf-8')}"

也可以用 PIL 重新編碼，一步到位地保證宣告與內容一致（還能順帶壓縮、剝離異常幀）：

import base64, io
from PIL import Image

def image_to_data_uri(image_path):
    img = Image.open(image_path)
    buf = io.BytesIO()
    img.convert("RGB").save(buf, format="JPEG", quality=90)
    b64 = base64.b64encode(buf.getvalue()).decode("utf-8")
    return f"data:image/jpeg;base64,{b64}"

自檢建議：file xxx.png（macOS / Linux 命令列）一秒看出檔案真實格式；Python 裡 Image.open(path).format 也能拿到。不同模型系列對 media type 的校驗嚴格程度不同——有的寬鬆放行，Claude 系（尤其經 Bedrock 通道）校驗最嚴。按”宣告必須與內容一致”來寫程式碼，在所有模型上都不會踩坑。

GPT-5 系列引數差異：若把示例中的模型換成 gpt-5.5 / gpt-5.4 等 GPT-5 系列，請注意：

用 max_completion_tokens 替代 max_tokens
temperature 只支援 1（預設即可，不要傳其它值）
不要傳 top_p 引數

Gemini、Claude 系列則無此限制，可正常使用 max_tokens、temperature 等引數。

🎯 常見應用場景

1. 商品識別與分析

prompt = """
請分析這張商品圖片，包括：
1. 商品型別和品牌
2. 主要特徵和賣點
3. 適合的目標使用者
4. 建議的營銷文案
"""

2. 文件 OCR 識別

prompt = """
請提取圖片中的所有文字內容，並按照原始格式整理輸出。
如果有表格，請用 Markdown 表格格式呈現。
"""

3. 醫學影像輔助分析

prompt = """
這是一張醫學影像圖片，請：
1. 描述影像的基本資訊（如成像型別、部位等）
2. 標註可見的解剖結構
3. 注意：僅供參考，不作為診斷依據
"""

4. 安全監控場景分析

prompt = """
分析監控畫面，識別：
1. 場景中的人數和位置
2. 是否有異常行為
3. 環境安全隱患
4. 時間戳資訊（如果可見）
"""

💡 最佳實踐

圖片預處理建議

格式支援：JPEG、PNG、GIF、WebP 等主流格式
大小限制：建議單張圖片不超過 20MB
解析度：高解析度圖片會獲得更好的識別效果
壓縮最佳化：適度壓縮以提高傳輸速度

提示詞最佳化

# ❌ 不推薦：模糊的提示
prompt = "看看這是什麼"

# ✅ 推薦：具體明確的提示
prompt = """
請從以下幾個方面分析這張圖片：
1. 主要物件：識別圖片中的主要物體或人物
2. 場景環境：描述拍攝地點和環境特徵
3. 色彩構圖：分析配色方案和構圖特點
4. 情感氛圍：圖片傳達的情緒或氛圍
5. 可能用途：這張圖片適合用於什麼場景
"""

錯誤處理

import requests
from requests.exceptions import RequestException

def analyze_image_with_retry(image_url, prompt, max_retries=3):
    """帶重試機制的影像分析函式"""
    for attempt in range(max_retries):
        try:
            response = requests.post(
                "https://api.apiyi.com/v1/chat/completions",
                headers={
                    "Authorization": f"Bearer {API_KEY}",
                    "Content-Type": "application/json"
                },
                json={
                    "model": "gpt-5.5",
                    "messages": [{
                        "role": "user",
                        "content": [
                            {"type": "text", "text": prompt},
                            {"type": "image_url", "image_url": {"url": image_url}}
                        ]
                    }]
                },
                timeout=30
            )
            
            if response.status_code == 200:
                return response.json()
            elif response.status_code == 429:
                print(f"速率限制，等待後重試... (嘗試 {attempt + 1}/{max_retries})")
                time.sleep(2 ** attempt)  # 指數退避
            else:
                print(f"錯誤: {response.status_code} - {response.text}")
                
        except RequestException as e:
            print(f"請求異常: {e}")
            
    return None

🔧 高階功能

1. 流式輸出

對於長篇分析，可以使用流式輸出獲得更好的使用者體驗：

payload = {
    "model": "gpt-5.5",
    "messages": [...],
    "stream": True
}

response = requests.post(url, headers=headers, json=payload, stream=True)
for line in response.iter_lines():
    if line:
        print(line.decode('utf-8'))

2. 多輪對話

保持上下文進行深入分析：

messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "這是什麼動物？"},
            {"type": "image_url", "image_url": {"url": "animal.jpg"}}
        ]
    },
    {
        "role": "assistant",
        "content": "這是一隻金毛尋回犬。"
    },
    {
        "role": "user",
        "content": [{"type": "text", "text": "它看起來多大了？健康狀況如何？"}]
    }
]

3. 結合函式呼叫

tools = [
    {
        "type": "function",
        "function": {
            "name": "save_image_analysis",
            "description": "儲存影像分析結果到資料庫",
            "parameters": {
                "type": "object",
                "properties": {
                    "objects": {"type": "array", "items": {"type": "string"}},
                    "scene": {"type": "string"},
                    "text_content": {"type": "string"}
                }
            }
        }
    }
]

payload = {
    "model": "gpt-5.5",
    "messages": messages,
    "tools": tools,
    "tool_choice": "auto"
}

📊 效能對比

模型	響應速度	識別準確度	中文支援	價格
Gemini 3.1 Pro Preview	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	$$
Gemini 3.5 Flash	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	$
GPT-5.5	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	$$
Claude Sonnet 4.6	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	$$
Gemini 2.5 Flash	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐	$

🚨 注意事項

隱私保護：不要上傳包含敏感資訊的圖片
合規使用：遵守相關法律法規，不用於非法用途
結果驗證：AI 分析結果僅供參考，重要決策需人工複核
成本控制：合理選擇模型，避免不必要的開銷

🔗 相關資源

💡 小貼士：建議先使用 Gemini 3.5 Flash 或 Gemini 2.5 Flash 等高性價比模型進行測試，確認效果後再切換到 Gemini 3.1 Pro、GPT-5.5 等高階模型進行生產部署。更多可用模型請檢視當下熱門模型或控制台模型列表。

產品基礎

基礎 API

圖片 API（官轉）

影片 API（官轉）

多模態理解 API

文本 API

🌟 核心特性

📋 支援的視覺模型

🚀 快速開始

1. 基礎示例 - 圖片 URL

2. 本地圖片示例 - Base64 編碼

3. 高階示例 - 多圖對比分析

4. cURL 示例（命令列）

5. 常見錯誤：圖片 URL 下載超時

6. 常見錯誤：invalid base64 data（URL 誤放進 Base64 欄位）

7. 常見錯誤：宣告的圖片格式與實際格式不符（media type mismatch）

🎯 常見應用場景

1. 商品識別與分析

2. 文件 OCR 識別

3. 醫學影像輔助分析

4. 安全監控場景分析

💡 最佳實踐

圖片預處理建議

提示詞最佳化

錯誤處理

🔧 高階功能

1. 流式輸出

2. 多輪對話

3. 結合函式呼叫

📊 效能對比

🚨 注意事項

🔗 相關資源

​🌟 核心特性

​📋 支援的視覺模型

​🚀 快速開始

​1. 基礎示例 - 圖片 URL

​2. 本地圖片示例 - Base64 編碼

​3. 高階示例 - 多圖對比分析

​4. cURL 示例（命令列）

​5. 常見錯誤：圖片 URL 下載超時

​6. 常見錯誤：invalid base64 data（URL 誤放進 Base64 欄位）

​7. 常見錯誤：宣告的圖片格式與實際格式不符（media type mismatch）

​🎯 常見應用場景

​1. 商品識別與分析

​2. 文件 OCR 識別

​3. 醫學影像輔助分析

​4. 安全監控場景分析

​💡 最佳實踐

​圖片預處理建議

​提示詞最佳化

​錯誤處理

​🔧 高階功能

​1. 流式輸出

​2. 多輪對話

​3. 結合函式呼叫

​📊 效能對比

​🚨 注意事項

​🔗 相關資源

🌟 核心特性

📋 支援的視覺模型

🚀 快速開始

1. 基礎示例 - 圖片 URL

2. 本地圖片示例 - Base64 編碼

3. 高階示例 - 多圖對比分析

4. cURL 示例（命令列）

5. 常見錯誤：圖片 URL 下載超時

6. 常見錯誤：invalid base64 data（URL 誤放進 Base64 欄位）

7. 常見錯誤：宣告的圖片格式與實際格式不符（media type mismatch）

🎯 常見應用場景

1. 商品識別與分析

2. 文件 OCR 識別

3. 醫學影像輔助分析

4. 安全監控場景分析

💡 最佳實踐

圖片預處理建議

提示詞最佳化

錯誤處理

🔧 高階功能

1. 流式輸出

2. 多輪對話

3. 結合函式呼叫

📊 效能對比

🚨 注意事項

🔗 相關資源