Sửa lỗi OpenCode "Model Does Not Support Image Input" — GPT & Claude Vision không hoạt động

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

Vấn đề trông như thế nào

• Bạn chuyển sang một model GPT hoặc Claude trong OpenCode, kéo vào một ảnh chụp màn hình, và hỏi "describe this image."
• Câu trả lời là một biến thể của "I can't read images", "image input is not supported for this model", hoặc model trả lời về một tên tệp (screenshot.png) thay vì nội dung thực tế.
• Cùng bức ảnh đó hoạt động bình thường khi bạn dán trực tiếp vào ChatGPT hoặc Claude.

Đây không phải giới hạn của model và không phải API key bị hỏng. gpt-5.5, claude-sonnet-4-6, claude-opus-4-7, claude-opus-4-8, và claude-haiku-4-5 đều chấp nhận đầu vào ảnh qua API Chat Completions tương thích OpenAI. Bức ảnh đơn giản là chưa bao giờ rời khỏi OpenCode.

Vì sao điều này xảy ra

OpenCode quyết định theo từng model liệu một tệp đính kèm có thể được gửi hay không, và liệu tệp đính kèm đó có thể là ảnh hay không. Nó đọc điều này từ cấu hình provider của bạn trong opencode.jsonc. Nếu mục model của bạn trông như thế này:

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

…thì OpenCode không có tín hiệu nào cho biết model nhận ảnh. Tùy theo bản build, nó hoặc từ chối đính kèm tệp hoặc chỉ truyền tên tệp đính kèm vào phần văn bản của prompt. Model nhận được "[attachment: diagram.png]" — một chuỗi, không phải bức ảnh — và trả lời chính xác rằng nó không được cung cấp ảnh.

Cách khắc phục là báo cho OpenCode hai điều một cách rõ ràng:

Một khi cả hai được thiết lập, OpenCode mã hóa base64 bức ảnh và gửi nó dưới dạng đầu vào vision đúng chuẩn — và model đọc được nó.

Cách khắc phục

1. Định vị opencode.jsonc của bạn

2. Thêm attachment + modalities vào từng model vision

Đây là một khối provider hoạt động được cho GPT và Claude trên một endpoint tương thích OpenAI:

{
  "$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"]
          }
        }
      }
    }
  }
}

Ví dụ đầy đủ bao gồm claude-opus-4-7, claude-opus-4-8, claude-haiku-4-5, và các biến thể reasoning nằm trong hướng dẫn thiết lập OpenCode. Bạn có thể bật đầu vào ảnh cho chỉ một model — chỉ model đó mới cần hai trường này.

3. Dùng đúng base URL

Host tương thích OpenAI là:

https://apimaster.ai/v1

Đừng dùng https://api.apimaster.ai/v1 — host có tiền tố api. có thể gây lỗi TLS / lỗi kết nối.

4. Khởi động lại OpenCode

Các thay đổi cấu hình được nạp khi khởi động. Thoát hoàn toàn và mở lại OpenCode, hoặc ít nhất bắt đầu một phiên mới, nếu không cấu hình cũ (không nhận ảnh) vẫn còn hiệu lực.

5. Ưu tiên upload cục bộ / base64 hơn URL công khai

Hãy upload một PNG/JPG cục bộ trong OpenCode — nó được chuyển thành một base64 data URL, đây là cách đáng tin cậy. Truyền trực tiếp một URL ảnh công khai có thể thất bại, vì phía upstream phải tải nó về và có thể gặp giới hạn về định dạng, kích thước, MIME, hoặc chống hotlink:

Error while downloading file. Upstream status code: 400.

Nếu bạn thấy lỗi đó, hãy chuyển sang một tệp cục bộ / base64 data URL thay vì URL từ xa.

Kiểm tra rằng nó hoạt động

Trong OpenCode

Chuyển sang apimaster/gpt-5.5 hoặc apimaster/claude-sonnet-4-6, upload một ảnh, và hỏi:

Describe the main content of this image.

Một cấu hình đúng sẽ trả về mô tả thực sự. Nếu nó vẫn chỉ thấy tên tệp, thì các trường attachment / modalities bị thiếu hoặc OpenCode chưa được khởi động lại.

Trực tiếp qua API (cô lập vấn đề)

Để xác nhận rằng bản thân endpoint xử lý được vision — tách bạch vấn đề cấu hình OpenCode khỏi vấn đề của provider — hãy gửi một ảnh base64. Không bao giờ hardcode key thật; hãy dùng biến môi trường:

export APIMASTER_API_KEY="your 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
  }'

Đổi model thành claude-sonnet-4-6 để kiểm tra Claude theo cách tương tự. Một phản hồi 200 mô tả được bức ảnh nghĩa là vision hoạt động ở tầng API — nên bất kỳ lỗi nào còn lại đều nằm ở phía cấu hình OpenCode.

Giữ an toàn cho API Key của bạn

• Không bao giờ đặt API key bên trong opencode.jsonc. Tệp đó chỉ chứa provider, models, và các khả năng.
• Cấu hình key thông qua luồng /connect của OpenCode, giao diện Connect Provider, hoặc một biến môi trường.
• Đừng dán key vào chat, ảnh chụp màn hình, issue, hoặc repo công khai. Nếu nó bị lộ, hãy thu hồi và tạo lại ngay trong bảng điều khiển provider của bạn.

APIMaster giúp gì

Nếu bạn muốn một endpoint tương thích OpenAI duy nhất nơi vision của GPT và Claude "chạy được ngay" với cấu hình ở trên, APIMaster được xây dựng đúng cho việc này:

Từ mức nạp $1, trả theo dùng, không cần đăng ký gói. Hướng dẫn thiết lập OpenCode từng bước đầy đủ — bao gồm cả đầu vào ảnh — nằm trong hướng dẫn cấu hình OpenCode.

Đăng ký trên APIMaster →

Hướng dẫn liên quan

• Hướng dẫn cấu hình OpenCode — thiết lập provider + vision đầy đủ
• Cách sửa lỗi Invalid API Key (OpenAI / Claude) — lỗi xác thực 401
• Sửa lỗi "api error 400 content blocked" — kiểm duyệt, không phải vision
• Tất cả hướng dẫn sửa lỗi API — chỉ mục đầy đủ

FAQ

OpenCode có hỗ trợ đầu vào ảnh không? Có. OpenCode có thể gửi ảnh tới bất kỳ model nào có khả năng vision, nhưng bạn phải khai báo attachment: true và modalities.input: ["text", "image"] cho model đó trong opencode.jsonc. Không có khai báo, nó chỉ gửi tên tệp.

Những model nào của APIMaster có thể đọc ảnh trong OpenCode? gpt-5.5, claude-sonnet-4-6, claude-opus-4-7, claude-opus-4-8, và claude-haiku-4-5 đều chấp nhận đầu vào ảnh. Hãy thêm hai trường khả năng vào từng model bạn muốn dùng với ảnh.

Vì sao model chỉ thấy tên tệp? OpenCode không chuyển tệp đính kèm thành đầu vào ảnh — thay vào đó nó đưa tên tệp đính kèm vào phần văn bản của prompt. Đây là dấu hiệu điển hình cho thấy các trường attachment / modalities bị thiếu.

Tôi đã thêm các trường mà vẫn lỗi. Giờ làm sao? Khởi động lại hoàn toàn OpenCode, bắt đầu một phiên mới, và xác nhận model đang hoạt động chính là model bạn đã cấu hình. Sau đó kiểm tra endpoint trực tiếp bằng lệnh curl base64 ở trên để xem vấn đề nằm ở OpenCode hay ở provider.

Vì sao một URL ảnh công khai lại báo lỗi? Phía upstream phải tải các URL từ xa về và có thể bị chặn bởi kích thước, định dạng, MIME, hoặc bảo vệ chống hotlink (Error while downloading file. Upstream status code: 400.). Hãy dùng upload cục bộ / base64 data URL thay thế.