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. 공개 URL보다 로컬 업로드 / base64를 우선하세요

OpenCode에 로컬 PNG/JPG를 업로드하세요 — base64 데이터 URL로 변환되며, 이것이 안정적인 경로입니다. 공개 이미지 URL을 직접 전달하면 업스트림이 이를 다운로드해야 하고 포맷, 크기, MIME, 핫링크 제한에 걸릴 수 있어 실패할 수 있습니다:

Error while downloading file. Upstream status code: 400.

이런 오류가 보이면 원격 URL 대신 로컬 파일 / base64 데이터 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="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
  }'

model을 claude-sonnet-4-6으로 바꾸면 같은 방식으로 Claude를 테스트할 수 있습니다. 이미지를 설명하는 200 응답이 나오면 API 레이어에서 비전이 작동하는 것이므로, 남은 실패는 모두 OpenCode 설정 쪽에 있습니다.

API 키를 안전하게 보관하기

• API 키를 opencode.jsonc 안에 절대 넣지 마세요. 그 파일에는 프로바이더, 모델, 기능만 담깁니다.
• 키는 OpenCode의 /connect 흐름, Connect Provider UI, 또는 환경 변수를 통해 설정하세요.
• 키를 채팅, 스크린샷, 이슈, 공개 저장소에 붙여넣지 마세요. 유출되면 프로바이더 콘솔에서 즉시 폐기하고 재발급하세요.

APIMaster가 어떻게 도움이 되는가

위 설정으로 GPT와 Claude 비전이 "그냥 작동하는" 단일 OpenAI 호환 엔드포인트를 원한다면, 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 데이터 URL을 사용하세요.