Community이미지github.com

steipete/nano-banana-pro

Nano Banana/Gemini 이미지 생성 및 편집: 텍스트/이미지 입력, 512~4K 워크플로우.

nano-banana-pro란 무엇인가요?

이 스킬은 Google의 Nano Banana 2 API(Gemini 3.1 Flash Image)를 활용하여 텍스트 프롬프트로 새로운 이미지를 생성하거나 기존 이미지를 편집하는 AI 에이전트 스킬입니다. 사용자는 CLI 명령어를 통해 512px부터 4K까지 다양한 해상도를 선택할 수 있으며, 빠른 초안 작업 후 최종 고해상도 이미지를 생성하는 단계별 워크플로우를 지원합니다. 주로 Claude Code, Codex, Cursor 등 터미널 기반 AI 코딩 에이전트에서 사용되며, `uv` 스크립트를 통해 실행됩니다. API 키는 명령줄 인자나 `GEMINI_API_KEY` 환경 변수로 설정할 수 있으며, 이미지 편집 시 입력 이미지 경로를 지정할 수 있습니다. 프롬프트 템플릿과 일반적인 오류 사전 점검 기능을 제공하여 사용자 경험을 향상시킵니다.

지원 대상~Claude Code✓Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/steipete/agent-scripts/tree/main/skills/nano-banana-pro

Installed? Explore more 이미지 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Nano Banana 2 이미지 생성 및 편집

Google의 Nano Banana 2 API(Gemini 3.1 Flash Image)를 사용하여 새 이미지를 생성하거나 기존 이미지를 편집합니다.

사용법

절대 경로를 사용하여 스크립트를 실행하세요(스킬 디렉토리로 cd하지 마세요):

새 이미지 생성:

uv run ~/.codex/skills/nano-banana-pro/scripts/generate_image.py --prompt "이미지 설명" --filename "출력-이름.png" [--resolution 512|1K|2K|4K] [--api-key KEY]

기존 이미지 편집:

uv run ~/.codex/skills/nano-banana-pro/scripts/generate_image.py --prompt "편집 지시사항" --filename "출력-이름.png" --input-image "입력/경로/이미지.png" [--resolution 512|1K|2K|4K] [--api-key KEY]

중요: 항상 사용자의 현재 작업 디렉토리에서 실행하여 이미지가 스킬 디렉토리가 아닌 사용자가 작업 중인 위치에 저장되도록 하세요.

기본 워크플로우 (초안 → 반복 → 최종)

목표: 프롬프트가 확정되기 전까지 4K에서 시간을 낭비하지 않고 빠르게 반복합니다.

  • 초안 (1K): 빠른 피드백 루프
    • uv run ~/.codex/skills/nano-banana-pro/scripts/generate_image.py --prompt "<초안 프롬프트>" --filename "yyyy-mm-dd-hh-mm-ss-draft.png" --resolution 1K
  • 반복: 프롬프트를 작은 차이로 조정하고, 실행마다 새 파일명을 유지하세요.
    • 편집 시: 만족할 때까지 매 반복마다 동일한 --input-image를 유지하세요.
  • 최종 (4K): 프롬프트가 확정된 경우에만 사용
    • uv run ~/.codex/skills/nano-banana-pro/scripts/generate_image.py --prompt "<최종 프롬프트>" --filename "yyyy-mm-dd-hh-mm-ss-final.png" --resolution 4K

해상도 옵션

Gemini 3.1 Flash Image API는 다음 출력 크기 값을 지원합니다:

  • 512 - 소형 ~512px급 해상도
  • 1K (기본값) - ~1024px 해상도
  • 2K - ~2048px 해상도
  • 4K - ~4096px 해상도

사용자 요청을 API 매개변수에 매핑:

  • "512", "512px", "0.5K", "썸네일", "작게" → 512
  • 해상도 언급 없음 → 1K
  • "저해상도", "1080", "1080p", "1K" → 1K
  • "2K", "2048", "보통", "중간 해상도" → 2K
  • "고해상도", "고해상", "Hi-Res", "4K", "울트라" → 4K

API 키

스크립트는 다음 순서로 API 키를 확인합니다:

  1. --api-key 인자 (사용자가 채팅에서 키를 제공한 경우 사용)
  2. GEMINI_API_KEY 환경 변수

둘 중 하나도 없으면 스크립트가 오류 메시지와 함께 종료됩니다.

사전 점검 + 일반적인 오류 (빠른 수정)

  • 사전 점검:

    • command -v uv (존재해야 함)
    • test -n "$GEMINI_API_KEY" (또는 --api-key 전달)
    • 편집 시: test -f "입력/경로/이미지.png"
  • 일반적인 오류:

    • Error: No API key provided. → GEMINI_API_KEY를 설정하거나 --api-key를 전달하세요.
    • Error loading input image: → 잘못된 경로 또는 읽을 수 없는 파일입니다. --input-image가 실제 이미지를 가리키는지 확인하세요.
    • "quota/permission/403" 스타일 API 오류 → 잘못된 키, 접근 권한 없음 또는 할당량 초과입니다. 다른 키/계정을 시도해보세요.

파일명 생성

패턴: yyyy-mm-dd-hh-mm-ss-name.png 형식으로 파일명을 생성합니다.

형식: {타임스탬프}-{설명적인-이름}.png

  • 타임스탬프: 현재 날짜/시간을 yyyy-mm-dd-hh-mm-ss 형식(24시간제)
  • 이름: 하이픈으로 연결된 소문자 설명 텍스트
  • 설명 부분은 간결하게 유지하세요(보통 1~5단어).
  • 사용자의 프롬프트나 대화 내용에서 맥락을 사용하세요.
  • 명확하지 않은 경우 무작위 식별자를 사용하세요(예: x9k2, a7b3).

예시:

  • 프롬프트 "조용한 일본식 정원" → 2025-11-23-14-23-05-japanese-garden.png
  • 프롬프트 "산 위의 일몰" → 2025-11-23-15-30-12-sunset-mountains.png
  • 프롬프트 "로봇 이미지 생성" → 2025-11-23-16-45-33-robot.png
  • 맥락 불명확 → 2025-11-23-17-12-48-x9k2.png

이미지 편집

사용자가 기존 이미지를 수정하려는 경우:

  1. 이미지 경로를 제공했는지 또는 현재 디렉토리의 이미지를 참조하는지 확인하세요.
  2. --input-image 매개변수에 이미지 경로를 사용하세요.
  3. 프롬프트에는 편집 지시사항이 포함되어야 합니다(예: "하늘을 더 극적으로", "사람 제거", "만화 스타일로 변경").
  4. 일반적인 편집 작업: 요소 추가/제거, 스타일 변경, 색상 조정, 배경 흐리게 처리 등.

프롬프트 처리

생성 시: 사용자의 이미지 설명을 그대로 --prompt에 전달하세요. 명확히 부족한 경우에만 다시 작성하세요.

편집 시: 편집 지시사항을 --prompt에 전달하세요(예: "하늘에 무지개 추가", "수채화 그림처럼 보이게").

두 경우 모두 사용자의 창의적 의도를 유지하세요.

프롬프트 템플릿 (높은 적중률)

사용자가 모호하거나 편집이 정확해야 하는 경우 템플릿을 사용하세요.

  • 생성 템플릿:

    • "<주제> 이미지를 생성하세요. 스타일: <스타일>. 구도: <카메라/샷>. 조명: <조명>. 배경: <배경>. 색상 팔레트: <팔레트>. 피할 것: <목록>."
  • 편집 템플릿 (나머지는 유지):

    • "변경: <단일 변경>만 수행하세요. 동일하게 유지: 주제, 구도/크롭, 자세, 조명, 색상 팔레트, 배경, 텍스트 및 전체 스타일. 새 객체를 추가하지 마세요. 텍스트가 있으면 변경하지 않고 유지하세요."

출력

  • PNG를 현재 디렉토리(또는 파일명에 디렉토리가 포함된 경우 지정된 경로)에 저장합니다.
  • 스크립트는 생성된 이미지의 전체 경로를 출력합니다.
  • 이미지를 다시 읽지 마세요 - 사용자에게 저장된 경로만 알려주세요.

예시

새 이미지 생성:

uv run ~/.codex/skills/nano-banana-pro/scripts/generate_image.py --prompt "벚꽃이 핀 조용한 일본식 정원" --filename "2025-11-23-14-23-05-japanese-garden.png" --resolution 4K

기존 이미지 편집:

uv run ~/.codex/skills/nano-banana-pro/scripts/generate_image.py --prompt "폭풍 구름으로 하늘을 더 극적으로 만들어줘" --filename "2025-11-23-14-25-30-dramatic-sky.png" --input-image "original-photo.jpg" --resolution 2K

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

steipete/agent-transcript

GitHub PR/issue agent transcripts: redact, preview, and insert safely.

steipete/beeper

Beeper cache: contact hints, room lookup, WhatsApp/iMessage traces, FTS.

steipete/browser-use

Existing Chrome automation: Chrome plugin first, mcporter fallback.

steipete/clawsweeper-status

ClawSweeper status: URLs, workflow health, active workers, ops snapshot.

steipete/clickclack

ClickClack ops: chat app, Hetzner deploy, DNS/docs/app, Docker rollout.

steipete/cloudflare-registrar

Cloudflare Registrar: domain availability, prices, registration via mcporter.

steipete/codex-debugging

Codex debugging: codex-rs core/tui/exec/cli/app-server/config.

steipete/create-cli

CLI UX/spec: args, flags, help, output, errors, config, dry-run.

steipete/discord-clawd

Discord-backed OpenClaw agent/session relay; not archive search.

steipete/domain-dns-ops

DNS/domain ops: registrars, zones, redirects, DNS/HTTP verify, manager truth.

steipete/frontend-design

Frontend UI: pages, apps, components, polished non-generic design.

steipete/github-author-context

GitHub contributor context: identity, activity, trust, company/team signal.

steipete/github-cache-hygiene

GitHub quota/cache hygiene: gh, ghx, xcache, gitcrawl, mirrors, limits.

steipete/github-deep-review

GitHub deep review: bugs, PRs, best fix, stale-or-real, read code first.

steipete/github-project-triage

GitHub issue/PR triage: queues, CI, blockers, risk, proof, next actions.

steipete/hopper-debugger

Hopper debugging: macOS/iOS binaries, ObjC/Swift symbols, dyld, LLDB.

steipete/instruments-profiling

Instruments/xctrace profiling: macOS/iOS traces, binaries, args, exports.

steipete/mac-maintenance

Mac upkeep: brew update/upgrade, pull clean repos, empty Trash.

steipete/maintainer-orchestrator

Open-source maintainer orchestration: Codex app workers, work recovery, dependencies, vision, releases.

steipete/markdown-converter

Markdown conversion: PDF, Office, HTML, data, OCR, audio, ZIP, YouTube.

관련 스킬