Claude Code 이미지 생성 방법: 코드 렌더링·스크립트·MCP 고르기

Claude Code에는 이미지를 그리는 기능이 없습니다. Anthropic 도움말은 Claude가 이미지 생성 도구처럼 사진이나 일러스트를 만들지 않는다고 밝히고, API 문서도 Claude를 이미지를 이해하는 모델로만 설명합니다(Anthropic 도움말, Vision 문서). 그래서 Claude Code 세션에서 나오는 이미지 파일의 출처는 둘뿐입니다.

• Claude가 작성해 실행한 코드가 그린 것: SVG, HTML, Python 같은 코드를 쓰고 렌더링해 PNG나 WebP로 저장합니다. 추가 요금이 없고 글자가 정확합니다.
• 외부 이미지 모델이 그린 것: Claude가 스크립트나 MCP 서버를 통해 OpenAI, Google, Hugging Face 같은 곳의 이미지 모델을 호출하고 결과를 파일로 받습니다. 요금은 Claude 구독과 별개로 그 서비스에서 청구됩니다.

어느 쪽을 쓸지는 필요한 이미지의 종류가 정합니다. 다이어그램, 차트, 아이콘, 제목이 들어간 커버는 코드로 그리는 편이 빠르고 정확합니다. 사진이나 일러스트가 필요하면 이미지 모델을 불러야 하고, 이때 혼자 쓰는지 팀이 저장소로 공유하는지에 따라 스크립트와 MCP 서버 중 하나를 고릅니다. 채팅 앱에서 Claude가 무엇을 만들 수 있는지는 Claude는 이미지를 생성할 수 있을까? Claude의 시각적 기능 완전 가이드에서 따로 다룹니다.

어떤 경로를 고를까: 이미지 종류와 결제 조건으로 정하기

아래 표는 2026년 10월 2일 기준 각 서비스 공식 문서의 조건입니다.

한 저장소에서 두 경로를 함께 쓰는 것도 흔합니다. 구조도는 SVG로, 히어로 이미지는 이미지 모델로 만드는 식입니다.

다이어그램·차트·글자 커버는 SVG를 써서 렌더링하기

도표와 글자가 중심인 이미지는 이미지 모델을 부르지 않는 편이 낫습니다. Claude가 좌표와 텍스트를 직접 쓰기 때문에 오탈자가 생기지 않고, 고칠 때도 파일의 해당 줄만 바꾸면 됩니다.

LaoZhang AI 블로그의 글 이미지가 이 방식으로 만들어집니다. Claude Code 안에서 Claude가 SVG를 쓰고, rsvg-convert가 정확한 크기의 PNG로 렌더링하고, cwebp가 WebP로 바꿉니다. 커버는 2400×1350, 본문 이미지는 2000×1125이며, 2026년 10월 2일에 발행된 글 한 편의 WebP 18장은 각각 136KB에서 192KB 사이였습니다. 이미지 모델 호출은 없습니다.

Claude Code에는 이렇게 요청하면 됩니다.

docs/architecture.svg 를 새로 작성해 줘. 2000×1125, 요청이 API 게이트웨이를 거쳐
워커 세 개로 나뉘는 흐름도. 글자는 한국어, 색은 프로젝트 README 의 브랜드 색.
작성 후 PNG 와 WebP 로 렌더링하고 결과를 직접 열어 겹친 글자가 없는지 확인해.

렌더링 명령은 두 줄입니다. macOS에서는 brew install librsvg webp로 두 도구를 설치합니다.

rsvg-convert -w 2000 -h 1125 docs/architecture.svg -o docs/architecture.png
cwebp -q 90 docs/architecture.png -o docs/architecture.webp

rsvg-convert 2.61.3에서 이 두 명령으로 2000×1125 PNG와 같은 크기의 WebP가 만들어집니다. SVG 안에 한글이 있으면 렌더링하는 컴퓨터에 설치된 글꼴이 쓰이므로, font-family에는 실제로 설치된 글꼴 이름을 적어야 합니다.

Anthropic이 공개한 anthropics/skills 저장소의 이미지 관련 스킬도 같은 부류입니다. canvas-design, algorithmic-art, slack-gif-creator는 PNG·PDF 레이아웃, p5.js, PIL 같은 코드로 그림을 만들며 이미지 모델을 호출하지 않습니다.

이 경로의 한계는 분명합니다. 자르기, 흑백 변환, 형식 변환 같은 가공은 Pillow로 할 수 있지만, 새로운 사진이나 손으로 그린 듯한 일러스트는 나오지 않습니다.

사진·일러스트는 스크립트로 OpenAI 이미지 API 호출하기

사진이나 일러스트가 필요하면 Claude가 실행할 수 있는 작은 스크립트 하나로 충분합니다. Claude는 프롬프트를 다듬고 명령을 실행하고, 스크립트가 API 응답을 디코딩해 프로젝트 폴더에 파일로 씁니다.

OpenAI의 현행 이미지 모델은 gpt-image-2.5-flare(빠른 일상용)와 gpt-image-2.5-sunburst(편집 정밀도)이고, 엔드포인트는 POST /v1/images/generations입니다. 응답은 URL이 아니라 base64 문자열(data[0].b64_json)이며 기본 형식은 PNG입니다(OpenAI 이미지 생성 가이드).

아래 generate.py는 Python 표준 라이브러리만 씁니다. 모델은 위 두 ID만 받고, 이미 있는 파일은 덮어쓰지 않으며, 키는 환경 변수에서 읽고 출력하지 않습니다.

#!/usr/bin/env python3
"""Generate one image with the OpenAI Images API and save it to disk.

Standard library only. Reads the key from OPENAI_API_KEY; never prints it.
"""
import argparse
import base64
import json
import os
import pathlib
import sys
import urllib.error
import urllib.request

MODELS = ("gpt-image-2.5-flare", "gpt-image-2.5-sunburst")


def main() -> int:
    parser = argparse.ArgumentParser()
    parser.add_argument("--prompt", required=True)
    parser.add_argument("--out", required=True, help="output file, e.g. assets/hero.png")
    parser.add_argument("--model", default="gpt-image-2.5-flare", choices=MODELS)
    parser.add_argument("--size", default="1536x1024")
    parser.add_argument("--quality", default="low")
    args = parser.parse_args()

    key = os.environ.get("OPENAI_API_KEY")
    if not key:
        print("OPENAI_API_KEY is not set. Export it in the shell before starting claude.", file=sys.stderr)
        return 2

    out = pathlib.Path(args.out)
    if out.exists():
        print(f"{out} already exists. Choose another --out so nothing is overwritten.", file=sys.stderr)
        return 2

    base = os.environ.get("OPENAI_BASE_URL", "https://api.openai.com/v1").rstrip("/")
    body = json.dumps({
        "model": args.model,
        "prompt": args.prompt,
        "size": args.size,
        "quality": args.quality,
    }).encode()
    request = urllib.request.Request(
        f"{base}/images/generations",
        data=body,
        headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
    )
    try:
        with urllib.request.urlopen(request, timeout=300) as response:
            payload = json.load(response)
    except urllib.error.HTTPError as error:
        print(f"HTTP {error.code}: {error.read().decode(errors='replace')[:600]}", file=sys.stderr)
        return 1
    except urllib.error.URLError as error:
        print(f"Request failed: {error.reason}", file=sys.stderr)
        return 1

    out.parent.mkdir(parents=True, exist_ok=True)
    out.write_bytes(base64.b64decode(payload["data"][0]["b64_json"]))
    print(json.dumps({"saved": str(out), "bytes": out.stat().st_size, "usage": payload.get("usage")}))
    return 0


if __name__ == "__main__":
    sys.exit(main())

이 스크립트로 확인된 범위는 거부 경로 네 가지이며, 실제 키로 이미지를 생성한 결과는 아닙니다. 2026년 10월 2일 Python 3.12.1에서 나온 결과는 다음과 같습니다.

따라서 실제 응답의 usage 모양, 장당 비용, 기본값(1536x1024, low)을 계정이 받아들이는지, 걸리는 시간은 첫 호출에서 직접 봐야 합니다. 요청 형식과 매개변수 값은 OpenAI 가이드에 적힌 그대로입니다. 권장 크기는 1024x1024, 1536x1024, 1024x1536이고 품질은 low부터 max까지 있으며, 복잡한 프롬프트는 2분가량 걸릴 수 있어 타임아웃을 300초로 잡았습니다.

실행 전에 걸리는 조건이 하나 있습니다. OpenAI는 GPT Image 모델을 쓰기 전에 조직 인증을 요구할 수 있고, 이 인증에는 지원 국가에서 발급된 실물 신분증이 필요하며 한 사람이 조직 하나만 인증할 수 있습니다(OpenAI 조직 인증 안내). 인증이 되지 않은 조직이라면 첫 호출이 오류로 돌아올 수 있습니다.

Google 나노바나나를 쓰고 싶다면 스크립트의 요청 부분이 달라집니다. 현행 모델 ID는 gemini-3.1-flash-lite-image, gemini-3.1-flash-image, gemini-3-pro-image이고, 구형 gemini-2.5-flash-image는 2026년 10월 2일에 종료되므로 예전 스크립트에 남아 있다면 바꿔야 합니다. 전체 설정은 Claude Code에 나노바나나 연결: 스킬·MCP와 현행 모델 ID에 있습니다.

스크립트를 스킬로 묶기: SKILL.md와 allowed-tools

같은 스크립트를 반복해 쓸 거라면 스킬로 만들어 두는 편이 편합니다. 프로젝트 스킬은 .claude/skills/NAME/SKILL.md에, 개인 스킬은 ~/.claude/skills/NAME/SKILL.md에 둡니다. Claude는 description을 보고 스킬을 쓸지 판단하며, /image처럼 이름으로 직접 불러도 됩니다(Claude Code 스킬 문서).

---
name: image
description: 사진이나 일러스트가 필요할 때 OpenAI 이미지 API로 한 장을 생성해 파일로 저장한다. 다이어그램과 차트에는 쓰지 않는다.
allowed-tools: Bash(python3 ${CLAUDE_SKILL_DIR}/scripts/generate.py *)
---

1. 용도와 구도를 한 문단의 영어 프롬프트로 정리한다.
2. 아래 명령을 한 번만 실행한다. --out 은 assets/ 아래의 새 파일명으로 한다.

   python3 ${CLAUDE_SKILL_DIR}/scripts/generate.py --prompt "..." --out assets/hero.png

3. 출력된 JSON 의 saved 경로와 usage 를 사용자에게 그대로 알려 준다.
4. 다시 생성하기 전에 반드시 사용자에게 묻는다.

generate.py는 .claude/skills/image/scripts/에 넣습니다. ${CLAUDE_SKILL_DIR}은 스킬 본문과 allowed-tools의 Bash 규칙 안에서 스킬 폴더 경로로 바뀝니다. 공식 문서의 예시는 Bash(${CLAUDE_SKILL_DIR}/scripts/render.sh *) 형태이고, 위 줄은 그 형식에 이 스크립트 경로를 넣은 것입니다.

스킬을 추가하거나 고치면 실행 중인 세션에 바로 반영됩니다. 세션을 시작할 때 최상위 skills 폴더 자체가 없었던 경우에만 /reload-skills가 필요합니다. 스킬을 처음 만든다면 Claude Code에서 먼저 써야 할 Skills (2026): 워크플로별 공식 스타터 가이드가 구조를 익히는 데 도움이 됩니다.

MCP 서버로 연결하기: Hugging Face·fal.ai·Replicate 명령

스크립트를 관리하고 싶지 않거나 여러 모델을 바꿔 가며 써 보려면 이미지 생성 도구를 가진 MCP 서버를 연결합니다. 아래 명령은 각 벤더의 공식 문서에 실린 Claude Code용 명령입니다.

Hugging Face. 공식 MCP 서버 README의 명령입니다. zsh에서는 URL의 ? 때문에 따옴표로 감싸야 합니다.

claude mcp add hf-mcp-server -t http "https://huggingface.co/mcp?login"

claude를 시작해 인증을 마친 뒤, huggingface.co/settings/mcp 에서 이미지 생성 Space를 추가해야 이미지 도구가 나타납니다. Hugging Face가 예로 드는 것은 FLUX와 Qwen 이미지 Space입니다.

fal.ai. fal MCP 문서의 명령입니다. MCP 서버 자체는 무료이고 실행한 모델만큼만 과금되며, run_model과 get_pricing 도구가 들어 있어 실행 전에 Claude에게 가격을 조회하게 할 수 있습니다.

claude mcp add --transport http fal-ai https://mcp.fal.ai/mcp --header "Authorization: Bearer YOUR_FAL_KEY"

이 명령은 키를 설정 파일에 평문으로 저장합니다. 저장소에 올라가는 프로젝트 범위 설정이라면 .mcp.json에서 ${FAL_KEY}처럼 환경 변수 확장을 쓰는 편이 안전합니다.

Replicate. Replicate MCP 안내의 명령이며, 추가한 뒤 세션에서 /mcp로 인증합니다.

claude mcp add replicate https://mcp.replicate.com/sse --transport sse --scope user

이 명령은 SSE 전송을 쓰는데, Claude Code MCP 문서는 SSE를 지원 중단 예정으로 표시하고 있습니다. 연결이 되지 않을 때는 이 전송 방식부터 의심하고 Replicate 문서에서 최신 명령을 다시 확인하면 됩니다.

연결 상태는 claude mcp list로 확인합니다. claude.ai의 커넥터 디렉터리에 있는 Adobe, Canva, Hugging Face 같은 파트너 커넥터는 claude.ai 계정으로 로그인한 Claude Code에서만 보이고, ANTHROPIC_API_KEY로 인증한 세션에는 나타나지 않습니다. Anthropic이 직접 만든 이미지 모델 커넥터는 없습니다.

MCP 도구가 PNG, JPEG, GIF, WebP를 돌려주면 Claude Code는 원본을 ~/.claude/projects/ 아래 세션의 tool-results 폴더에 저장하고 그 경로를 Claude에게 알려 줍니다. 이 동작에는 Claude Code v2.1.283 이상이 필요합니다. 파일이 프로젝트 폴더 밖에 있으므로 "방금 받은 이미지를 assets/hero.png 로 복사해 줘"라고 한 번 더 요청해야 합니다. 이미지 데이터를 돌려주는 도구도 출력 토큰 한도(기본 25,000)의 적용을 받으며, 큰 이미지에서 잘린다면 MAX_MCP_OUTPUT_TOKENS를 올리는 방법밖에 없습니다. 각 서버가 이미지 자체를 돌려주는지 URL을 돌려주는지는 서버 문서에 따라 다르며, URL을 받았다면 Claude에게 내려받아 저장하게 하면 됩니다.

스크립트와 MCP 중 무엇을 쓸까: 파일 위치·키·팀 공유 차이

팀이 같은 방식으로 반복해 쓸 이미지라면 스크립트를 넣은 프로젝트 스킬이, 혼자 여러 모델을 시험해 볼 때는 MCP 서버가 맞습니다. 차이는 네 가지에서 나옵니다.

저장소에 들어 있는 프로젝트 스킬은 실행하기 전에 읽어 봐야 합니다. 프로젝트 스킬의 allowed-tools는 작업 공간 신뢰 확인을 거치지 않는다고 공식 문서가 경고하고 있어, 남이 만든 저장소의 스킬이 어떤 명령을 승인 없이 돌리는지는 SKILL.md를 열어야 알 수 있습니다.

장당 비용 계산: Gemini $0.067, Cloudflare 하루 약 173장

이미지 모델 요금은 Claude Pro나 Max 구독에 포함되지 않고 호출한 서비스에서 따로 나갑니다. 2026년 10월 2일 기준 공식 요금은 다음과 같습니다.

출처는 OpenAI 요금표, Gemini API 요금표, Workers AI 요금표, ZeroGPU 문서입니다.

Gemini는 장수를 곱하면 됩니다. 히어로 이미지 한 장을 고르려고 1K 시안을 20장 뽑으면 20 × $0.067 = $1.34입니다. 같은 작업을 4K로 하면 20 × $0.151 = $3.02가 됩니다. 시안은 낮은 해상도로 뽑고 고른 것만 다시 생성하면 차이가 그대로 절약됩니다.

OpenAI에는 공식 장당 가격이 없습니다. 요금이 토큰으로 계산되고 이미지 한 장의 토큰 수는 크기와 품질에 따라 달라지므로, 첫 호출 뒤 응답의 usage를 읽어 출력 토큰 수 × $30 ÷ 1,000,000으로 계산해야 합니다. 위 스크립트가 usage를 그대로 출력하는 이유입니다. Tier 1 계정은 분당 이미지 5장으로 제한됩니다. 토큰 과금 구조는 GPT Image 2.5 Sunburst 가격: 호출당 $0.03과 공식 토큰 요금 비교에서 자세히 볼 수 있습니다.

Cloudflare의 무료 한도는 장수로 환산할 수 있습니다. @cf/black-forest-labs/flux-1-schnell은 512×512 타일 하나에 4.80 Neurons, 스텝 하나에 9.60 Neurons이고 기본 스텝은 4입니다(모델 문서). 1024×1024 이미지를 타일 4개로 보면 4 × 4.80 + 4 × 9.60 = 57.6 Neurons이고, 10,000 ÷ 57.6 ≈ 173이므로 하루 약 173장입니다. 타일 수를 4로 가정했고 같은 계정의 다른 Workers AI 사용이 없을 때의 추정치입니다. 한도는 매일 00:00 UTC에 초기화되고, 넘으면 요청이 실패합니다. 공식 호출 예시는 다음과 같으며 응답은 base64로 인코딩된 JPEG입니다.

curl https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/run/@cf/black-forest-labs/flux-1-schnell \
  -X POST \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -d '{ "prompt": "cyberpunk cat" }'

Hugging Face의 무료 범위는 장수가 아니라 시간입니다. 무료 계정은 하루 GPU 5분이고 첫 사용 24시간 뒤에 초기화됩니다. 몇 장이 나오는지는 Space와 모델에 따라 달라집니다.

호출당 고정 가격이 필요하거나 OpenAI 조직 인증, Gemini 결제 설정을 진행하기 어려운 경우에는 제3자 API 서비스가 선택지가 됩니다. 이 블로그를 운영하는 laozhang.ai는 OpenAI Images 호환 엔드포인트에서 gpt-image-2.5-sunburst-vip와 gpt-image-2.5-flare-vip를 호출당 $0.03에 제공한다고 문서에 적고 있습니다(laozhang.ai 문서, 2026년 9월 12일 기준 가격). OpenAI가 아닌 제3자 서비스이므로 OpenAI의 약관, 데이터 정책, SLA는 적용되지 않습니다. 위 스크립트에서 쓰려면 MODELS 허용 목록에 이 ID를 추가하고 OPENAI_BASE_URL을 https://api2.laozhang.ai/v1로 지정해야 하는데, 이 조합으로 실제 생성이 되는지는 확인된 바 없습니다.

자동 승인과 API 키: allow 규칙은 무인 유료 호출이 됩니다

이미지 생성 명령은 매번 승인하는 상태로 두는 것이 기본값으로 맞습니다. 승인 창에서 "Yes, and don't ask again"을 고르면 .claude/settings.local.json에 allow 규칙이 기록되고, 그 뒤로는 Claude가 판단할 때마다 유료 호출이 사람 확인 없이 나갑니다(권한 문서).

스킬의 allowed-tools는 범위가 더 좁습니다. 스킬을 호출한 그 턴에만 권한을 주고 다음 메시지에서 사라지므로, "스킬을 부른 한 번"만 승인 없이 실행됩니다. 반면 설정 파일의 allow 규칙은 세션 전체에 계속 적용됩니다.

{
  "permissions": {
    "allow": ["Bash(python3 .claude/skills/image/scripts/generate.py *)"],
    "deny": ["Read(./.env)"]
  }
}

위 allow 줄은 문서의 규칙 형식에 이 스크립트 경로를 넣은 예이며, 넣는 순간 실행 한 번이 곧 결제 한 번이 됩니다. 시안을 여러 장 뽑는 작업을 맡길 때만 잠시 넣고 끝나면 지우거나, 프롬프트에 "최대 4장까지만"처럼 상한을 명시하는 편이 안전합니다. 문서는 Bash 인자를 제한하는 규칙이 깨지기 쉽다고도 경고하므로, 규칙만으로 장수를 통제할 수 있다고 기대해서는 안 됩니다. deny 줄은 키가 들어 있는 파일을 Claude가 읽지 못하게 하는 문서 권장 설정입니다.

키를 두는 곳도 정해 두어야 합니다.

• 셸 환경 변수는 claude가 시작될 때 읽힙니다. 키를 바꿨다면 Claude Code를 다시 시작해야 합니다.
• 설정의 env 키는 세션과 하위 프로세스에 변수를 넣어 줍니다. 커밋되는 설정 파일에 키를 적으면 저장소에 그대로 남습니다.
• claude mcp add --env KEY=value는 값을 설정에 그대로 기록합니다. .mcp.json은 ${VAR} 확장을 지원하므로 공유 설정에는 변수 이름만 적습니다.
• 키를 프롬프트에 붙여 넣지 않는 편이 좋습니다. 셸에서 설정해 두고 Claude에게는 변수 이름만 알려 주면 스크립트가 알아서 읽습니다.

생성한 이미지를 Claude가 보고 고치게 하기: Read 도구의 한계

Claude Code는 이미지를 만들지는 못해도 볼 수는 있어서, 생성한 뒤 확인하고 고치는 과정을 한 세션에서 돌릴 수 있습니다. Read 도구는 PNG, JPG 같은 파일을 Claude가 볼 수 있는 시각 정보로 돌려주고, 드래그 앤 드롭이나 Ctrl+V(Windows·WSL은 Alt+V) 붙여넣기, 파일 경로 지정도 됩니다(도구 레퍼런스).

SVG 경로에서는 이 과정이 특히 잘 맞습니다. "렌더링한 PNG를 열어서 글자가 상자를 넘치는 곳을 찾아 SVG를 고쳐 줘"라고 하면 Claude가 좌표를 수정하고 다시 렌더링합니다. 이미지 모델 경로에서는 Claude가 결과를 보고 프롬프트를 고쳐 다시 호출하게 되므로, 확인 한 번이 유료 호출 한 번으로 이어진다는 점이 다릅니다.

Claude가 보는 것은 원본 해상도가 아닙니다. 큰 이미지는 축소·재압축되고, v2.1.196부터는 축소 후에도 500KB를 넘으면 더 낮은 품질의 JPEG로 다시 인코딩됩니다. 작은 글자나 가장자리 품질을 확인해야 한다면 해당 부분만 잘라서 보여 주는 것이 문서가 권하는 방법입니다.

Claude Code 이미지 생성에 대해 자주 헷갈리는 점

Claude Code로 이미지를 무료로 생성할 수 있나요?

SVG 같은 코드 렌더링은 추가 요금 없이 됩니다. 이미지 모델 쪽에서 공식 문서로 확인되는 무료 범위는 Cloudflare Workers AI의 하루 10,000 Neurons와 Hugging Face ZeroGPU의 무료 계정 하루 GPU 5분, 두 가지입니다. OpenAI GPT Image 2.5와 Gemini 이미지 모델에는 무료 등급이 없습니다.

Codex CLI를 거쳐 ChatGPT 구독으로 이미지를 만드는 스킬은 어떤가요?

Claude Code에서 Codex CLI를 불러 ChatGPT 구독의 이미지 생성을 쓰는 스킬이 공유되고 있습니다. API 키로 호출해 호출마다 과금되는 위 경로들과 달리 구독 한도를 쓰는 방식이므로, 한도와 허용 범위는 해당 스킬의 설명과 OpenAI의 안내를 직접 확인해야 합니다.

스킬, MCP 서버, 커넥터는 무엇이 다른가요?

스킬은 Claude가 따를 지침과 스크립트를 담은 폴더이고, MCP 서버는 Claude Code에 도구를 추가하는 외부 프로세스나 원격 서비스입니다. 커넥터는 claude.ai 계정에 연결해 두는 MCP 서버로, claude.ai 계정으로 로그인한 Claude Code에서만 나타납니다. 이미지 생성에서는 스킬이 "스크립트를 어떻게 실행할지"를, MCP 서버와 커넥터가 "어떤 이미지 도구를 쓸 수 있는지"를 정합니다.

생성된 이미지는 어디에 저장되나요?

스크립트 경로에서는 --out으로 지정한 프로젝트 안 경로에 저장됩니다. MCP 경로에서는 Claude Code v2.1.283 이상일 때 ~/.claude/projects/ 아래 세션의 tool-results 폴더에 저장되므로, 프로젝트에서 쓰려면 Claude에게 복사를 요청해야 합니다.