OpenCode AI API 金鑰設定 — 相容 OpenAI 的配置方式

如何透過 APIMaster.ai 的自訂 API 金鑰設定 OpenCode AI。在 opencode.jsonc 中將 APIMaster 新增為相容 OpenAI 的提供者，即可存取 Claude、GPT-5.5 與 DeepSeek，支援圖片輸入（Vision）與可選用的 Reasoning 層級。

OpenCode Desktop 是 OpenCode 的圖形化用戶端（目前為 Beta 版）：支援本地代理工作階段、檔案編輯和 Shell 執行。APIMaster.ai 是 OpenAI 相容的服務 — 可在 設定 → 提供者 → 自訂提供者 中新增。

請先取得您的 API 金鑰。下方使用佔位符 your_apimaster_key；螢幕截圖已遮蓋真實金鑰。

先決條件

從 opencode.ai/download 安裝 OpenCode Desktop。
- Windows：opencode-desktop-win-x64.exe
- macOS：brew install --cask opencode-desktop 或 .dmg
- Linux：.deb / .rpm / AppImage
從控制台取得 APIMaster API 金鑰。

步驟 1 — 開啟提供者

啟動 OpenCode Desktop 並開啟一個工作區。
按一下齒輪圖示（左下角）。
在側邊欄中選取 Providers（提供者）。
向下捲動到 Custom provider（自訂提供者）（通過 Base URL 新增 OpenAI 相容的提供者）。
按一下 + Connect（連線）。

設定 → 提供者 → 自訂提供者

步驟 2 — 自訂提供者表單

欄位	值
Provider ID（提供者 ID）	`apimaster`
Display name（顯示名稱）	`APIMaster.ai`
Base URL	`https://apimaster.ai/v1`
API key（API 金鑰）	您的 APIMaster 金鑰

自訂提供者表單

除非僅透過 Header 進行驗證，否則請將 Headers 保留空白。

步驟 3 — 新增模型並提交

在下一個畫面中，對應模型（左側 = OpenCode 中的標籤，右側 = 發送給 APIMaster 的 模型 ID — 通常相同）：

左側	右側
`gpt-5.4`	`gpt-5.4`
`claude-sonnet-4-6`	`claude-sonnet-4-6`

按一下 + Add model（新增模型）以增加更多行。
按一下 Submit（提交）。

新增模型並提交

從市集挑選 ID。在代理對話中避免使用純圖像生成模型（例如 gpt-image-2）。

需要圖片辨識（Vision）？ gpt-5.5、claude-sonnet-4-6、claude-opus-4-7、claude-opus-4-8、claude-haiku-4-5 等模型支援圖片輸入，但在 OpenCode 中還需額外宣告能力，見為 GPT 和 Claude 設定圖片輸入能力。

步驟 4 — 選擇模型

開始或開啟一個工作階段。
開啟輸入欄下方的模型下拉選單。
在 APIMaster.ai 下方，選擇一個模型（例如 claude-sonnet-4-6）。

模型選取器

步驟 5 — 測試

發送 hello 或一個小型程式碼任務。正常取得 Assistant 回覆（檔案編輯 / Shell）表示 APIMaster 已連線。

聊天測試

進階：`opencode.jsonc` 與推理

上述 UI 流程已足夠快速入門。若要為相同的模型 ID 設定推理／思考努力層級（low、high、max 等），請編輯 opencode.jsonc。

設定檔位置

作業系統	路徑
macOS / Linux	`~/.config/opencode/opencode.jsonc`
Windows	`C:\Users\<username>\.config\opencode\opencode.jsonc`

如果檔案不存在，請建立它。儲存後請重新啟動 OpenCode Desktop 或開始一個新的工作階段。

API 金鑰（請勿放入 jsonc）

請勿將您的 API 金鑰存放在 opencode.jsonc 中。

請使用：

終端機中的 /connect，或
設定 → 提供者 → 連線提供者（與上述步驟 1–2 相同）。

將金鑰存放在 OpenCode 的驗證儲存區；jsonc 僅定義提供者、模型和推理變體。

jsonc 中的 APIMaster 提供者

提供者 ID：apimaster。npm 套件：@ai-sdk/openai-compatible。

baseURL 必須是：

https://apimaster.ai/v1

不是 https://apimaster.ai/ — OpenCode 會附加 /chat/completions。沒有 /v1 時會變成 https://apimaster.ai/chat/completions → 404 找不到。

也不要寫成 https://api.apimaster.ai/v1：帶 api. 前綴的位址在測試中可能造成 TLS／連線失敗。正確的位址是 https://apimaster.ai/v1。

包含推理變體的完整範例 — 下載並覆蓋 OpenCode 的設定檔：

下載 opencode.jsonc
覆蓋（或另存為）：
- macOS / Linux：~/.config/opencode/opencode.jsonc
- Windows：C:\Users\<username>\.config\opencode\opencode.jsonc
透過 /connect 或 UI 設定 API 金鑰（絕不放在 jsonc 中）。
重新啟動 OpenCode Desktop 或開始一個新的工作階段。

覆蓋前請備份現有檔案，或僅合併 provider.apimaster 區塊。

最小範例：

{
  "$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"]
          },
          "variants": {
            "low": { "reasoningEffort": "low" },
            "high": { "reasoningEffort": "high" }
          }
        }
      }
    }
  }
}

上方 gpt-5.5 中的 attachment 與 modalities 欄位用於啟用圖片輸入（Vision），詳見下方為 GPT 和 Claude 設定圖片輸入能力。若只需文字對話，可省略這兩個欄位。

推理原則

variants = UI 中為一個模型 ID 提供的多個推理層級。
對於 OpenAI 相容的 API，OpenCode 將 reasoningEffort 映射為請求體中的 reasoning_effort。
變體名稱應與實際參數相符（high → "reasoningEffort": "high"）。
每個模型支援不同的層級 — 請依照官方文件設定；沒有隱藏的重新對應。

各模型的推理層級

模型	推理變體	備註
`gpt-5.4`	`low`, `medium`, `high`, `xhigh`	GPT 推理
`gpt-5.5`	`low`, `medium`, `high`, `xhigh`	GPT 推理
`deepseek-v4-flash`	`high`, `max`	DeepSeek 思考（建議）
`deepseek-v4-pro`	`high`, `max`	DeepSeek 思考（建議）
`claude-sonnet-4-6`	`low`, `medium`, `high`, `max`	Claude Sonnet 努力
`claude-opus-4-7`	`low`, `medium`, `high`, `xhigh`, `max`	Claude Opus 努力
`claude-opus-4-8`	`low`, `medium`, `high`, `xhigh`, `max`	Claude Opus 努力
`claude-haiku-4-5`	無	無未確認的努力層級
`minimax-m3`	無	無未確認的努力層級

完整檔案請見 opencode.jsonc。

在 OpenCode 中切換推理

儲存 opencode.jsonc 後重新啟動 OpenCode Desktop，或新開工作階段。
使用輸入欄下方的模型／推理下拉選單（例如 gpt-5.4 / high）。
若您的版本支援：可用 Ctrl + Shift + D 在推理層級間循環切換。

為 GPT 和 Claude 設定圖片輸入能力

APIMaster.ai 的 gpt-5.5、claude-sonnet-4-6、claude-opus-4-7、claude-opus-4-8、claude-haiku-4-5 等模型都支援圖片輸入 / Vision：可讀取截圖、照片、圖表等做辨識、描述、OCR 或看圖寫程式。

關鍵：模型支援圖片 ≠ OpenCode 會把圖片傳給模型。 即使 APIMaster.ai 的模型本身支援圖像辨識，也必須在 opencode.jsonc 中為該模型宣告能力。否則 OpenCode 可能不會把圖片內容當成多模態輸入送出，而只是把附件名／檔名塞進 prompt，導致模型回覆類似「目前的模型不支援讀取圖片輸入」。

需要宣告的兩個欄位

為每個要用於圖片的模型加上：

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

attachment: true：告訴 OpenCode 這個模型允許傳送附件。
modalities.input 含 "image"：告訴 OpenCode 這個模型支援圖片輸入，OpenCode 才會把圖片轉成多模態 image_url 內容送出。

完整範例（涵蓋 GPT 和 Claude）

可直接下載 opencode.jsonc（已內建以下欄位），或把下方 provider.apimaster 區塊合併進您現有的設定：

{
  "$schema": "https://opencode.ai/config.json",
  "disabled_providers": [],
  "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"]
          },
          "variants": {
            "low": { "reasoningEffort": "low" },
            "medium": { "reasoningEffort": "medium" },
            "high": { "reasoningEffort": "high" },
            "xhigh": { "reasoningEffort": "xhigh" }
          }
        },
        "claude-sonnet-4-6": {
          "name": "claude-sonnet-4-6",
          "attachment": true,
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "variants": {
            "low": { "reasoningEffort": "low" },
            "medium": { "reasoningEffort": "medium" },
            "high": { "reasoningEffort": "high" },
            "max": { "reasoningEffort": "max" }
          }
        },
        "claude-opus-4-7": {
          "name": "claude-opus-4-7",
          "attachment": true,
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "variants": {
            "low": { "reasoningEffort": "low" },
            "medium": { "reasoningEffort": "medium" },
            "high": { "reasoningEffort": "high" },
            "xhigh": { "reasoningEffort": "xhigh" },
            "max": { "reasoningEffort": "max" }
          }
        },
        "claude-opus-4-8": {
          "name": "claude-opus-4-8",
          "attachment": true,
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "variants": {
            "low": { "reasoningEffort": "low" },
            "medium": { "reasoningEffort": "medium" },
            "high": { "reasoningEffort": "high" },
            "xhigh": { "reasoningEffort": "xhigh" },
            "max": { "reasoningEffort": "max" }
          }
        },
        "claude-haiku-4-5": {
          "name": "claude-haiku-4-5",
          "attachment": true,
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          }
        }
      }
    }
  }
}

說明：

只想啟用 gpt-5.5 的圖片輸入，就只給 gpt-5.5 加 attachment 和 modalities；其他模型可不動。
只想啟用 Claude，就只給 Claude 模型加這些欄位。
保留各模型原有的 Reasoning variants（low / medium / high / xhigh / max），圖片欄位與推理互不衝突。
修改 opencode.jsonc 後必須完全退出並重新啟動 OpenCode，或至少新開一個工作階段，讓設定重新載入。
API 金鑰不要寫進這個檔案，仍透過 /connect 或 UI 連線提供者 設定（見下方安全說明）。

圖片來源：優先本地上傳／base64

建議在 OpenCode 中上傳本地 PNG / JPG。理想情況下 OpenCode 會把圖片轉成 base64 data URL（data:image/png;base64,...）再傳給 APIMaster——這是已驗證可行的方式。
直接傳公開圖片 URL 可能失敗。APIMaster／上游在下載公開圖片時可能因網路、格式、大小、MIME、防盜連等原因回傳：
```
Error while downloading file. Upstream status code: 400.
```
遇到此類錯誤，請改用 base64 data URL 或本地圖片上傳，不要依賴模型端去下載公開 URL。

測試圖片辨識是否生效

方式一：在 OpenCode 中測試

在模型下拉中切換到 apimaster/gpt-5.5 或 apimaster/claude-sonnet-4-6。
上傳一張 PNG / JPG 圖片。

輸入：

請描述這張圖片的主要內容。

設定正確時，模型應能描述圖片內容。
若模型只提到檔名／附件名，或回覆「不支援讀取圖片輸入」，通常表示 OpenCode 沒有把圖片內容真正傳給模型——回去檢查該模型的 attachment 與 modalities 欄位，並重新啟動 OpenCode。

方式二：用 API 直接測試

用於區分「APIMaster 模型問題」還是「OpenCode 轉接層問題」。請勿寫入真實金鑰，改用環境變數。

Linux / macOS：

export APIMASTER_API_KEY="你的 APIMaster API Key"

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": "請描述這張圖片。" },
          {
            "type": "image_url",
            "image_url": {
              "url": "data:image/png;base64,這裡放圖片base64"
            }
          }
        ]
      }
    ],
    "max_tokens": 1000
  }'

把 model 換成 claude-sonnet-4-6 即可用同樣方式測試 Claude（已驗證回傳 HTTP 200 且能辨識圖片）。

Windows PowerShell：

$env:APIMASTER_API_KEY = "你的 APIMaster API Key"
# 將本地圖片轉成 base64 後，作為 data:image/png;base64,... 放入 image_url.url
# 再用相同 JSON 請求體呼叫 https://apimaster.ai/v1/chat/completions

回傳 200 且能描述圖片，表示 APIMaster 側的圖片輸入正常；此時若 OpenCode 內仍無法辨識，問題出在 OpenCode 的 attachment / modalities 設定或未重新啟動。

常見問題

圖片輸入 / Vision

為什麼 OpenCode 提示「目前的模型不支援讀取圖片」？

APIMaster.ai 的 gpt-5.5 和部分 Claude 模型本身支援圖片輸入，這個提示通常表示 OpenCode 沒有把圖片當成多模態輸入傳給模型。

檢查 opencode.jsonc 中對應模型是否設定了：

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

確認改設定後已重新啟動 OpenCode。
確認 baseURL 為 https://apimaster.ai/v1。
確認 APIMaster API 金鑰有效。
若用公開圖片 URL 失敗，改用 base64 data URL 或本地圖片上傳。

為什麼模型只看到附件名、看不到圖片內容？

通常是 OpenCode 沒有把附件讀取並轉成圖片輸入，而是只把附件名／檔名放進 prompt。
請啟用 attachment: true 和 modalities.input: ["text", "image"]，並使用支援圖片輸入的模型。

為什麼公開圖片 URL 會報錯？

APIMaster 或上游下載公開圖片時可能受網路、格式、檔案大小、MIME、防盜連或代理限制。
若出現 Error while downloading file. Upstream status code: 400.，請改用 base64 data URL。

設定 attachment 後仍不生效怎麼辦？

完全退出並重新啟動 OpenCode。
新開一個工作階段再測試。
檢查目前工作階段實際使用的 model 是否就是已設定圖片欄位的那個模型。
檢查 API 金鑰是否有效。
檢查 OpenCode 記錄檔是否有 401 / 400 / unsupported image / invalid content type 等錯誤。
用方式二：用 API 直接測試的 base64 圖片，區分是 APIMaster 模型問題還是 OpenCode 轉接層問題。

安全注意事項

不要把 APIMaster API 金鑰寫入 opencode.jsonc；該檔案只放提供者、模型、圖片能力與推理。
不要把金鑰貼到聊天、截圖、issue、公開文件或程式碼倉庫。
金鑰若曾出現在截圖或記錄檔中，請立即到控制台作廢並重新產生，再在 OpenCode 中更新提供者。
建議透過 OpenCode 的 /connect 連線流程、環境變數或本地憑證儲存來管理 API 金鑰。
OpenCode 會在本機工作區讀寫檔案、執行 Shell 指令，請只在可信任的工作區中使用。

圖片輸入檢查清單

baseURL 為 https://apimaster.ai/v1（不是 https://api.apimaster.ai/v1）
使用支援 Vision 的模型，例如 gpt-5.5 或支援 Vision 的 Claude 模型
對應模型已設定 attachment: true
對應模型的 modalities.input 含 "image"
修改 opencode.jsonc 後已重新啟動 OpenCode
API 金鑰有效
測試圖片為常見格式（PNG / JPG）
若公開圖片 URL 失敗，已改用 base64 data URL