Vision API 요청을 위해 이미지를 Base64로 변환하는 방법

Vision API에 Base64가 필요한 이유

OpenAI GPT-4o, Google Cloud Vision, Anthropic Claude, Qwen-VL 등 최신 Vision API는 이미지를 두 가지 방식으로 받습니다: 이미지를 가리키는 공개 URL이거나, 이미지 원본 데이터를 Base64 문자열로 인코딩하여 JSON 요청 본문에 직접 포함하는 방식입니다.

이미지가 이미 온라인에 호스팅되어 있다면 URL 방식이 간단합니다. 하지만 실제 업무에서는 이미지가 로컬에 있는 경우가 많습니다: 방금 찍은 스크린샷, 스캔한 문서, 동영상에서 추출한 프레임, 개발 파이프라인의 테스트 이미지 등. 이런 경우 Base64 인코딩이 적합합니다. 서버에 먼저 업로드할 필요 없이 이미지를 API 요청에 직접 포함할 수 있습니다.

Base64를 사용한 일반적인 Vision API 요청은 다음과 같습니다:

{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What's in this image?"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/png;base64,iVBORw0KGgo..."
          }
        }
      ]
    }
  ]
}

문제는 로컬 파일에서 해당 Base64 문자열을 만드는 과정입니다. 특히 개발 및 테스트 중에 이 작업을 반복해야 하는 경우 더욱 그렇습니다.

일반적인 방법 (그리고 그 단점)

1. Python 스크립트

import base64

with open("screenshot.png", "rb") as f:
    encoded = base64.b64encode(f.read()).decode()
print(encoded)

잘 작동하지만, Python이 설치되어 있어야 하고 스크립트를 작성(또는 찾기)해야 하며, 터미널에서 출력을 복사해야 합니다. 다른 이미지를 반복적으로 테스트하는 경우 매번 이 스크립트를 실행하고 출력을 JSON에 수동으로 붙여넣어야 합니다.

2. 명령줄

# macOS / Linux
base64 -i screenshot.png | pbcopy

# Windows PowerShell
[Convert]::ToBase64String([IO.File]::ReadAllBytes("screenshot.png")) | Set-Clipboard

구문을 기억하고 있다면 빠르지만, 출력은 단순한 문자열일 뿐입니다. 올바른 이미지인지, 인코딩이 정확한지 확인할 수 없습니다. API 요청을 보내고 결과를 확인하기 전까지는 알 수 없습니다.

3. 온라인 Base64 변환기

많은 웹사이트가 드래그 앤 드롭 파일-Base64 변환을 제공합니다. 분명한 문제: 파일을 다른 사람의 서버에 업로드해야 합니다. 테스트 스크린샷이라면 괜찮을 수 있지만, 독점 데이터, 내부 문서, 의료 이미지, NDA 적용 대상 파일에는 사용할 수 없습니다.

더 나은 방법: 붙여넣기, 미리보기, 복사

ViewJSON은 더 간단한 워크플로를 제공합니다. 이미지를 편집기에 직접 붙여넣으면 Base64 문자열을 즉시 얻을 수 있으며, 모든 것이 브라우저 안에서 처리됩니다:

1. ViewJSON 열기 — viewjson.net에 접속합니다
2. 이미지 붙여넣기 — 파일 탐색기, 스크린샷 도구, 브라우저, 디자인 앱 등 어디에서든 이미지를 복사하여 JSON 편집기에 Ctrl+V로 직접 붙여넣습니다
3. 미리보기 확인 — ViewJSON이 자동으로 이미지를 Base64로 변환하여 JSON 문자열 값으로 삽입합니다. 인라인 이미지 미리보기가 즉시 표시되어 올바른 이미지인지 확인할 수 있습니다.
4. Base64 복사 — 복사 버튼을 클릭하거나 문자열 값을 선택합니다. API 요청 페이로드에 바로 붙여넣을 수 있는 완전한 Base64 인코딩 문자열을 얻습니다.

전체 워크플로 데모:

대용량 Base64 문자열 처리

Base64 인코딩 이미지는 매우 길 수 있습니다. 고해상도 JPEG 하나가 100,000자 이상의 문자열을 생성할 수 있습니다. 편집기의 반응성을 유지하기 위해 ViewJSON은 긴 문자열의 표시를 자동으로 잘라냅니다. 하지만 잘라내기는 표시에만 해당됩니다.

잘린 Base64 값을 복사하면 ViewJSON의 무손실 클립보드 복원 메커니즘이 작동합니다. 잘린 문자열을 복사하고 있음을 감지하고 클립보드에 전체 원본 콘텐츠를 자동으로 복원합니다. 손상된 파일을 생성하는 잘린 버전이 아닌, 항상 완전하고 수정되지 않은 Base64 문자열을 얻을 수 있습니다.

완전한 API 페이로드 구성

Base64 문자열을 얻은 후에는 올바른 API 형식으로 래핑해야 합니다. 가장 많이 사용되는 Vision API의 예시입니다:

OpenAI GPT-4o Vision

{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "Describe this image" },
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/png;base64,<YOUR_BASE64_HERE>"
          }
        }
      ]
    }
  ],
  "max_tokens": 300
}

Google Cloud Vision

{
  "requests": [
    {
      "image": {
        "content": "<YOUR_BASE64_HERE>"
      },
      "features": [
        { "type": "TEXT_DETECTION" }
      ]
    }
  ]
}

ViewJSON에 이미지를 붙여넣은 후 생성된 Base64 문자열을 복사하여 API 요청 페이로드에 삽입하세요. ViewJSON의 API 요청 빌더를 사용하여 URL, 메서드, 헤더, 본문을 설정한 후 전체 요청을 cURL 명령으로 내보낼 수도 있습니다.

프라이버시: 업로드 불필요

온라인 Base64 변환기 웹사이트와 달리, ViewJSON은 전적으로 브라우저에서 실행됩니다. 이미지-Base64 변환은 브라우저의 내장 FileReader API를 사용하여 로컬에서 처리됩니다. 이미지가 어떤 서버로도 전송되지 않습니다.

따라서 민감한 이미지 변환에 적합합니다: 헬스케어 AI API용 의료 스캔, OCR 서비스용 내부 문서, 비주얼 검색 시스템용 독점 제품 이미지, 또는 서드파티 변환기에 업로드하고 싶지 않은 모든 파일.

방법 비교