APIMaster.ai
APIMaster.ai 문서
Quick startAPIMaster.aiMarketplace

OpenCode AI API 키 설정 — OpenAI 호환 구성

APIMaster.ai의 커스텀 API 키로 OpenCode AI를 설정하는 방법. opencode.jsonc에서 APIMaster를 OpenAI 호환 제공자로 추가하고, Claude, GPT-5.5, DeepSeek을 이미지 입력(Vision) 및 선택적 Reasoning 등급과 함께 사용하세요.

OpenCode Desktop은 OpenCode의 그래픽 클라이언트(현재 베타)입니다: 로컬 에이전트 세션, 파일 편집, 셸 실행. APIMaster.ai는 OpenAI 호환입니다 — 설정 → 제공자 → 사용자 정의 제공자에서 추가하세요.

먼저 API 키 받기. 아래에서 your_apimaster_key를 플레이스홀더로 사용하세요; 스크린샷은 실제 키를 가립니다.

사전 요구 사항

  1. opencode.ai/download에서 OpenCode Desktop 설치.
    • Windows: opencode-desktop-win-x64.exe
    • macOS: brew install --cask opencode-desktop 또는 .dmg
    • Linux: .deb / .rpm / AppImage
  2. 콘솔에서 APIMaster API 키.

1단계 — 제공자 열기

  1. OpenCode Desktop을 실행하고 워크스페이스를 엽니다.
  2. 기어 아이콘(왼쪽 아래)을 클릭합니다.
  3. 사이드바에서 제공자를 선택합니다.
  4. 사용자 정의 제공자(기본 URL로 OpenAI 호환 제공자 추가)로 스크롤합니다.
  5. + 연결을 클릭합니다.

설정 → 제공자 → 사용자 정의 제공자

2단계 — 사용자 정의 제공자 양식

필드 값
제공자 ID apimaster
표시 이름 APIMaster.ai
기본 URL https://apimaster.ai/v1
API 키 사용자의 APIMaster 키

사용자 정의 제공자 양식

헤더 전용으로 인증하지 않는 한 헤더는 비워 둡니다.

3단계 — 모델 추가 및 제출

다음 화면에서 모델을 매핑합니다(왼쪽 = OpenCode의 레이블, 오른쪽 = APIMaster로 보내지는 모델 id — 일반적으로 동일함):

왼쪽 오른쪽
gpt-5.4 gpt-5.4
claude-sonnet-4-6 claude-sonnet-4-6
  1. + 모델 추가를 클릭하여 더 많은 행을 추가합니다.
  2. 제출을 클릭합니다.

모델 추가 및 제출

마켓플레이스에서 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단계 — 모델 선택

  1. 세션을 시작하거나 엽니다.
  2. 입력 아래의 모델 드롭다운을 엽니다.
  3. APIMaster.ai 아래에서 모델(예: claude-sonnet-4-6)을 선택합니다.

모델 선택기

5단계 — 테스트

hello 또는 작은 코딩 작업을 보냅니다. 정상적인 Assistant 응답(파일 편집/셸)이 오면 APIMaster가 연결된 것입니다.

채팅 테스트

고급: opencode.jsonc 및 Reasoning

위의 UI 흐름은 빠른 시작에 충분합니다. 동일한 모델 id에 대해 Reasoning / thinking effort 계층(low, high, max, …)을 구성하려면 **opencode.jsonc**를 편집하세요.

설정 파일 위치

OS 경로
macOS / Linux ~/.config/opencode/opencode.jsonc
Windows C:\Users\<사용자 이름>\.config\opencode\opencode.jsonc

파일이 없으면 생성하세요. 저장 후 OpenCode Desktop을 다시 시작하거나 새 세션을 시작하세요.

API 키 (jsonc에 넣지 마세요)

API 키를 opencode.jsonc에 저장하지 마세요.

대신 다음을 사용하세요:

  • 터미널에서 /connect, 또는
  • 설정 → 제공자 → 제공자 연결(위 1-2단계와 동일).

비밀은 OpenCode의 인증 저장소에 보관하고, jsonc는 제공자, 모델 및 Reasoning 변형만 정의합니다.

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 Not Found가 발생합니다.

또한 https://api.apimaster.ai/v1도 아닙니다 — api. 접두사 호스트는 테스트에서 TLS / 연결 실패를 일으킬 수 있습니다. 올바른 호스트는 https://apimaster.ai/v1입니다.

Reasoning 변형을 포함한 전체 예제 — 다운로드하여 OpenCode의 설정을 덮어쓰기:

  1. opencode.jsonc 다운로드
  2. 다음 위치에 덮어쓰기(또는 저장):
    • macOS / Linux: ~/.config/opencode/opencode.jsonc
    • Windows: C:\Users\<사용자 이름>\.config\opencode\opencode.jsonc
  3. /connect 또는 UI를 통해 API 키 설정 (절대 jsonc에 넣지 않음).
  4. 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에서 이미지 입력 활성화를 참조하세요. 텍스트 채팅만 필요하면 생략하세요.

Reasoning 원칙

  • variants = UI에서 하나의 모델 id에 대한 여러 Reasoning 계층.
  • OpenAI 호환 API의 경우 OpenCode는 reasoningEffort를 요청 본문의 **reasoning_effort**로 매핑합니다.
  • 변형 이름은 실제 매개변수와 일치해야 합니다(high → "reasoningEffort": "high").
  • 각 모델은 서로 다른 계층을 지원합니다 — 공식 문서에 따라 구성하고, 숨겨진 재매핑은 없습니다.

모델별 Reasoning 계층

모델 Reasoning 변형 비고
gpt-5.4 low, medium, high, xhigh GPT reasoning
gpt-5.5 low, medium, high, xhigh GPT reasoning
deepseek-v4-flash high, max DeepSeek thinking (권장)
deepseek-v4-pro high, max DeepSeek thinking (권장)
claude-sonnet-4-6 low, medium, high, max Claude Sonnet effort
claude-opus-4-7 low, medium, high, xhigh, max Claude Opus effort
claude-opus-4-8 low, medium, high, xhigh, max Claude Opus effort
claude-haiku-4-5 없음 확인되지 않은 effort 계층 없음
minimax-m3 없음 확인되지 않은 effort 계층 없음

전체 파일은 opencode.jsonc를 참조하세요.

OpenCode에서 Reasoning 전환

  1. opencode.jsonc를 저장한 후 다시 시작하거나 새 세션을 시작하세요.
  2. 모델/Reasoning 드롭다운(예: gpt-5.4 / high)을 사용하세요.
  3. 빌드에서 지원되는 경우: **Ctrl + Shift + D**로 Reasoning 계층을 순환합니다.

GPT 및 Claude에서 이미지 입력 활성화

gpt-5.5, claude-sonnet-4-6, claude-opus-4-7, claude-opus-4-8, claude-haiku-4-5 같은 APIMaster.ai 모델은 이미지 입력 / Vision을 지원합니다 — 스크린샷, 사진, 차트를 읽어 인식, 설명, OCR을 하거나 이미지로부터 코딩할 수 있습니다.

모델이 이미지를 지원한다 ≠ OpenCode가 이미지를 전송한다. APIMaster.ai 모델 자체가 vision을 지원하더라도, opencode.jsonc에서 기능을 선언해야 합니다. 그렇지 않으면 OpenCode가 이미지를 멀티모달 입력으로 전송하지 않고 — 단지 첨부 파일 / 파일 이름만 프롬프트에 넣어, 모델이 "현재 모델은 이미지 입력을 지원하지 않습니다" 같은 응답을 할 수 있습니다.

선언해야 하는 두 필드

이미지와 함께 사용하려는 각 모델에 다음을 추가하세요:

"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 변형(low / medium / high / xhigh / max)을 유지하세요 — 이미지 필드와 Reasoning은 충돌하지 않습니다.
  • opencode.jsonc를 편집한 후 OpenCode를 완전히 종료하고 다시 시작하거나, 최소한 새 세션을 시작하여 설정을 다시 로드하세요.
  • 이 파일에 절대 API 키를 넣지 마세요 — /connect 또는 UI를 통해 구성하세요(아래 보안 참조).

이미지 소스: 로컬 업로드 / base64 권장

  • 권장: OpenCode에서 로컬 PNG / JPG를 업로드하세요. 이상적으로는 OpenCode가 APIMaster로 전송하기 전에 base64 데이터 URL(data:image/png;base64,...)로 변환합니다 — 이것이 검증된 작동 경로입니다.
  • 공개 이미지 URL을 직접 전달하면 실패할 수 있습니다. APIMaster / 업스트림이 네트워크, 형식, 크기, MIME, 핫링크 보호로 인해 공개 이미지를 다운로드하지 못하고 다음을 반환할 수 있습니다:
    Error while downloading file. Upstream status code: 400.
    이 경우 모델 측이 공개 URL을 다운로드하도록 의존하지 말고 base64 데이터 URL 또는 로컬 업로드를 사용하세요.

이미지 인식이 작동하는지 테스트

옵션 A — OpenCode에서 테스트

  1. 모델 드롭다운에서 apimaster/gpt-5.5 또는 **apimaster/claude-sonnet-4-6**로 전환합니다.
  2. PNG / JPG 이미지를 업로드합니다.
  3. 다음을 입력합니다:
    Describe the main content of this image.
  • 올바른 설정에서 모델은 이미지 콘텐츠를 설명해야 합니다.
  • 모델이 파일 / 첨부 이름만 언급하거나 "image input not supported"라고 응답하면, OpenCode가 이미지 콘텐츠를 전송하지 않는 것일 가능성이 높습니다 — 모델의 attachment와 modalities 필드를 확인하고 OpenCode를 다시 시작하세요.

옵션 B — API를 직접 통해 테스트

APIMaster 모델 문제와 OpenCode 어댑터 문제를 구분하는 데 유용합니다. 실제 키를 하드코딩하지 마세요 — 환경 변수를 사용하세요.

Linux / macOS:

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도 동일하게 테스트하세요(이미지 인식으로 HTTP 200 검증됨).

Windows PowerShell:

$env:APIMASTER_API_KEY = "your APIMaster API key"
# Convert a local image to base64, put it into image_url.url as data:image/png;base64,...
# Then call https://apimaster.ai/v1/chat/completions with the same JSON body.

이미지를 설명하는 200 응답은 APIMaster 측에서 이미지 입력이 작동함을 의미합니다; OpenCode가 여전히 실패하면 문제는 OpenCode의 attachment / modalities 설정 또는 재시작 누락에 있습니다.

문제 해결

UI 설정

문제 해결
401 키 확인; 노출된 경우 교체
모델을 찾을 수 없음 기본 URL은 https://apimaster.ai/v1이어야 함; 모델 id는 마켓플레이스와 일치해야 함
APIMaster 모델 없음 설정에서 제공자 편집 → 매핑 추가 → 제출
느림/시간 초과 다른 모델 시도; API 키 테스터 사용

Reasoning / jsonc

DeepSeek에는 왜 high와 max만 있나요?
DeepSeek의 공식 OpenAI 호환 thinking effort는 **high**와 **max**입니다. 예측 불가능하게 재매핑되는 low/medium/xhigh는 피하세요.

Claude Sonnet에는 왜 max가 있고 xhigh가 없나요?
Sonnet의 최상위 계층은 **max**입니다; **xhigh**는 Opus(claude-opus-4-7 / claude-opus-4-8)용입니다.

Haiku나 MiniMax M3에는 왜 변형이 없나요?
문서화된 reasoningEffort 값이 없으므로 변형을 건너뛰세요 — 모델은 여전히 작동합니다. UI에 Reasoning 하위 계층이 표시되지 않을 뿐입니다.

여전히 400 오류가 발생하나요?

  1. baseURL = https://apimaster.ai/v1 (사이트 루트 아님).
  2. 모델 id 철자가 마켓플레이스와 일치하는지 확인.
  3. /connect 또는 UI를 통해 키 구성.
  4. 일시적으로 variants를 제거 — 일반 요청이 작동하면 선택한 reasoning_effort가 해당 모델에서 지원되지 않을 수 있습니다.

이미지 입력 / 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 데이터 URL 또는 로컬 업로드를 사용하세요.

모델이 왜 이미지가 아닌 첨부 이름만 보나요?

  • 보통 OpenCode가 첨부 파일을 읽어 이미지 입력으로 변환하지 않고 — 단지 파일 / 첨부 이름만 프롬프트에 넣은 것입니다.
  • attachment: true와 modalities.input: ["text", "image"]를 활성화하고, 이미지 입력을 지원하는 모델을 사용하세요.

공개 이미지 URL이 왜 오류가 나나요?

  • APIMaster 또는 업스트림이 공개 이미지를 다운로드할 때 네트워크, 형식, 파일 크기, MIME, 핫링크 보호 또는 프록시에 의해 제한될 수 있습니다.
  • Error while downloading file. Upstream status code: 400.가 발생하면 base64 데이터 URL로 전환하세요.

attachment를 추가한 후에도 여전히 작동하지 않나요?

  1. OpenCode를 완전히 종료하고 다시 시작하세요.
  2. 새 세션을 시작하여 테스트하세요.
  3. 세션의 활성 모델이 이미지 필드로 구성한 모델인지 확인하세요.
  4. API 키가 유효한지 확인하세요.
  5. OpenCode 로그에서 401 / 400 / unsupported image / invalid content type 오류를 확인하세요.
  6. APIMaster 모델 문제와 OpenCode 어댑터 문제를 구분하려면 base64 이미지로 옵션 B — API를 직접 통해 테스트를 사용하세요.

보안

  • APIMaster API 키를 opencode.jsonc에 넣지 마세요; 그 파일은 제공자, 모델, 이미지 기능, Reasoning만 담습니다.
  • 채팅, 스크린샷, 이슈, 공개 문서 또는 코드 저장소에 키를 붙여넣지 마세요.
  • 스크린샷이나 로그에 나타난 키는 교체하세요 — 콘솔에서 취소하고 재생성한 후 OpenCode에서 제공자를 업데이트하세요.
  • API 키 관리는 OpenCode의 /connect 흐름, 환경 변수 또는 로컬 자격 증명 저장소를 선호하세요.
  • OpenCode는 파일을 읽고 쓰고 셸 명령을 실행할 수 있습니다 — 신뢰할 수 있는 워크스페이스에서만 사용하세요.

체크리스트

  • OpenCode Desktop 설치됨
  • 사용자 정의 제공자 연결됨 또는 opencode.jsonc에 apimaster 있음
  • 기본 URL / baseURL = https://apimaster.ai/v1 (https://apimaster.ai/ 아님)
  • /connect 또는 UI를 통해 API 키 설정 (jsonc에 없음)
  • 하나 이상의 채팅 모델 매핑됨
  • (선택 사항) Reasoning 변형이 공식 계층과 일치
  • 테스트 메시지 성공

이미지 입력 체크리스트

  • 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 데이터 URL 시도함

요약

  • 키: baseURL (https://apimaster.ai/v1), 모델 id, API 키 (/connect 또는 UI), 선택적 Reasoning 변형.
  • 변형 이름 = 실제 reasoning_effort 값.
  • 모델별로 계층 구성; 지원되지 않는 경우 변형 건너뛰기(Haiku, MiniMax M3).

함께 보기