修正 OpenCode「模型不支援圖片輸入」——GPT 與 Claude 視覺功能失效

"attachment": true,
"modalities": {
  "input": ["text", "image"],
  "output": ["text"]
}

這個問題長什麼樣

• 你在 OpenCode 切換到 GPT 或 Claude 模型，拖入一張截圖，問「描述這張圖片」。
• 回覆卻是類似 「我無法讀取圖片」、「此模型不支援圖片輸入」，或是模型針對檔名（screenshot.png）而非實際內容作答。
• 同一張圖片直接貼到 ChatGPT 或 Claude 裡卻運作正常。

這不是模型的限制，也不是API 金鑰壞了。gpt-5.5、claude-sonnet-4-6、claude-opus-4-7、claude-opus-4-8 與 claude-haiku-4-5 全都能透過 OpenAI 相容的 Chat Completions API 接受圖片輸入。只是圖片根本沒離開 OpenCode。

為什麼會發生

OpenCode 是逐模型決定是否能送出附件，以及該附件能否是圖片。它從 opencode.jsonc 裡的供應商設定讀取這項資訊。如果你的模型項目長這樣：

"gpt-5.5": {
  "name": "gpt-5.5"
}

……那麼 OpenCode 就沒有任何訊號知道這個模型可以接受圖片。視版本而定，它要嘛拒絕附加檔案，要嘛只把附件名稱塞進提示文字裡。模型收到的是 "[attachment: diagram.png]"——一個字串，而非圖片——於是正確地回覆說沒有收到圖片。

修正方法是明確告訴 OpenCode 兩件事：

兩者都設定好之後，OpenCode 就會把圖片做 base64 編碼，並以正確的視覺輸入送出——模型也就能讀取它了。

如何修正

1. 找到你的 opencode.jsonc

2. 為每個視覺模型加上 attachment + modalities

以下是在 OpenAI 相容端點上，可運作的 GPT 與 Claude 供應商區塊：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "apimaster": {
      "name": "APIMaster.ai",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://apimaster.ai/v1"
      },
      "models": {
        "gpt-5.5": {
          "name": "gpt-5.5",
          "attachment": true,
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          }
        },
        "claude-sonnet-4-6": {
          "name": "claude-sonnet-4-6",
          "attachment": true,
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          }
        }
      }
    }
  }
}

涵蓋 claude-opus-4-7、claude-opus-4-8、claude-haiku-4-5 以及推理變體的完整範例，請見 OpenCode 設定指南。你可以只為單一模型啟用圖片輸入——只有那個模型需要這兩個欄位。

3. 使用正確的 base URL

OpenAI 相容主機為：

https://apimaster.ai/v1

請勿使用 https://api.apimaster.ai/v1——帶 api. 前綴的主機可能導致 TLS／連線失敗。

4. 重啟 OpenCode

設定變更是在啟動時載入的。完全結束並重新開啟 OpenCode，或至少開一個新工作階段，否則舊的（看不到圖片的）設定仍會生效。

5. 優先使用本機上傳／base64，而非公開 URL

在 OpenCode 裡上傳本機的 PNG/JPG——它會被轉換成 base64 data URL，這是最可靠的路徑。直接傳入公開圖片 URL可能失敗，因為上游必須下載它，並可能碰到格式、大小、MIME 或防盜連的限制：

Error while downloading file. Upstream status code: 400.

若你看到這個錯誤，請改用本機檔案／base64 data URL，而不是遠端 URL。

測試是否成功

在 OpenCode 裡

切換到 apimaster/gpt-5.5 或 apimaster/claude-sonnet-4-6，上傳一張圖片，然後問：

Describe the main content of this image.

設定正確的話會回傳真正的描述。如果它仍然只看到檔名，代表 attachment / modalities 欄位缺失，或是 OpenCode 沒有重啟。

直接透過 API（隔離問題）

要確認端點本身能處理視覺——把 OpenCode 設定問題和供應商問題區分開——請送出一張 base64 圖片。絕不要把真實金鑰寫死；請使用環境變數：

export APIMASTER_API_KEY="你的 APIMaster API 金鑰"

curl https://apimaster.ai/v1/chat/completions \
  -H "Authorization: Bearer $APIMASTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "Describe this image." },
          {
            "type": "image_url",
            "image_url": { "url": "data:image/png;base64,YOUR_IMAGE_BASE64" }
          }
        ]
      }
    ],
    "max_tokens": 1000
  }'

把 model 換成 claude-sonnet-4-6 即可用同樣方式測試 Claude。若回傳 200 且描述了圖片，代表視覺功能在 API 層運作正常——那麼剩下的任何失敗都出在 OpenCode 設定端。

保護好你的 API 金鑰

• 絕不要把 API 金鑰放進 opencode.jsonc。該檔案只存放供應商、模型與能力設定。
• 透過 OpenCode 的 /connect 流程、Connect Provider UI 或環境變數來設定金鑰。
• 不要把金鑰貼到聊天、截圖、issue 或公開儲存庫裡。萬一外洩，立刻在供應商後台撤銷並重新產生。

APIMaster 如何幫上忙

如果你想要一個單一的 OpenAI 相容端點，讓 GPT 與 Claude 視覺功能搭配上述設定「開箱即用」，APIMaster 正是為此打造：

最低 $1 儲值起，用多少付多少，無需訂閱。包含圖片輸入在內的完整 OpenCode 逐步設定，請見 OpenCode 設定指南。

前往 APIMaster 註冊 →

相關指南

• OpenCode 設定指南 — 完整供應商 + 視覺設定
• 如何修正無效的 API 金鑰（OpenAI / Claude） — 401 認證錯誤
• 修正「api error 400 content blocked」 — 是內容審核，不是視覺
• 所有 API 錯誤修正指南 — 完整索引

FAQ

OpenCode 到底支不支援圖片輸入？ 支援。OpenCode 可以把圖片送給任何具備視覺能力的模型，但你必須在 opencode.jsonc 裡為該模型宣告 attachment: true 與 modalities.input: ["text", "image"]。沒有這項宣告，它就只會送出檔名。

在 OpenCode 裡有哪些 APIMaster 模型能讀取圖片？ gpt-5.5、claude-sonnet-4-6、claude-opus-4-7、claude-opus-4-8 與 claude-haiku-4-5 全都接受圖片輸入。為每個你想搭配圖片使用的模型加上這兩個能力欄位即可。

為什麼模型只看到檔名？ OpenCode 沒有把附件轉換成圖片輸入——它反而把附件名稱塞進了提示文字。這是 attachment / modalities 欄位缺失的明顯徵兆。

我加了欄位但還是失敗，接下來怎麼辦？ 完全重啟 OpenCode、開一個新工作階段，並確認目前使用的模型正是你設定的那個。然後用上面的 base64 curl 直接測試端點，判斷問題出在 OpenCode 還是供應商。

為什麼公開圖片 URL 會出錯？ 上游必須下載遠端 URL，可能因大小、格式、MIME 或防盜連保護而被擋（Error while downloading file. Upstream status code: 400.）。請改用本機上傳／base64 data URL。