修复 OpenCode「模型不支持图片输入」——GPT 与 Claude 视觉失效

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

这个问题长什么样

• 你在 OpenCode 里切换到某个 GPT 或 Claude 模型，拖入一张截图，问「描述这张图片」。
• 回复是各种版本的 "我无法读取图片"、"该模型不支持图片输入"，或者模型回答的是一个文件名（screenshot.png），而非真实内容。
• 同一张图片直接粘贴到 ChatGPT 或 Claude 里却完全正常。

这不是模型的限制，也不是 API Key 坏了。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 中的 provider 配置里读取这一信息。如果你的模型条目长这样：

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

……那么 OpenCode 没有任何信号表明该模型能接收图片。根据构建版本不同，它要么拒绝附加文件，要么只把附件名传进提示词文本里。模型收到的是 "[attachment: diagram.png]"——一个字符串，而不是图片——于是它正确地回复自己没有拿到图片。

修复方法是明确告诉 OpenCode 两件事：

两者都设置好后，OpenCode 会把图片进行 base64 编码，作为标准的视觉输入发送出去——模型就能读到它了。

如何修复

1. 找到你的 opencode.jsonc

2. 给每个视觉模型加上 attachment + modalities

下面是一个在 OpenAI 兼容端点上可用的 GPT 与 Claude provider 配置块：

{
  "$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 配置问题与 provider 问题区分开——发送一张 base64 图片。永远不要硬编码真实 Key；使用环境变量：

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": "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 Key

• 绝不要把 API Key 放进 opencode.jsonc。该文件只保存 provider、模型和能力声明。
• 通过 OpenCode 的 /connect 流程、Connect Provider 界面或环境变量来配置 Key。
• 不要把 Key 粘贴到聊天、截图、issue 或公开仓库里。一旦泄露，立即在你的 provider 控制台吊销并重新生成。

APIMaster 如何帮到你

如果你想要一个单一的 OpenAI 兼容端点，让 GPT 和 Claude 视觉配合上述配置「开箱即用」，APIMaster 正是为此而生：

最低 $1 充值，按量付费，无订阅。包括图片输入在内的完整 OpenCode 分步配置，见 OpenCode 配置指南。

注册 APIMaster →

相关指南

• OpenCode 配置指南 —— 完整的 provider + 视觉配置
• 如何修复无效的 API Key（OpenAI / Claude） —— 401 鉴权错误
• 修复「api error 400 content blocked」 —— 内容审核，不是视觉问题
• 所有 API 错误修复指南 —— 完整索引

常见问题

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 还是 provider。

为什么公网图片 URL 会报错？ 上游必须下载远程 URL，可能被大小、格式、MIME 或防盗链保护拦截（Error while downloading file. Upstream status code: 400.）。改用本地上传 / base64 data URL。