|

OpenClaw를 사용하여 Nano Banana Pro 이미지 API를 연동하는 5단계 전체 튜토리얼

ByAPIYI - Stable and affordable AI API

OpenClaw AI Agent가 자동으로 이미지를 생성하게 만드는 것은 많은 개발자가 구현하고 싶어 하는 기능이죠. 이번 글에서는 5단계를 통해 OpenClaw용 커스텀 Skill을 만들고, Nano Banana Pro 이미지 생성 API를 연결하여 채팅 명령만으로 이미지가 자동 생성되는 전체 워크플로우를 구현하는 방법을 소개합니다.

핵심 가치: 이 글을 다 읽고 나면 OpenClaw 커스텀 Skill 제작 방법을 마스터하게 됩니다. 또한, APIYI 플랫폼을 통해 Nano Banana Pro를 연결하여 텍스트-이미지 변환, 이미지 편집, 일괄 처리를 구현함으로써 여러분의 AI Agent에 전문가 수준의 이미지 생성 능력을 부여할 수 있습니다.

openclaw-nano-banana-pro-image-api-tutorial-ko 图示

Nano Banana Pro 이미지 API 핵심 능력 개요

본격적인 연결에 앞서, Nano Banana Pro가 여러분의 OpenClaw Agent에 어떤 능력을 제공할 수 있는지 먼저 살펴보겠습니다.

Nano Banana Pro(공식 명칭: Gemini 3 Pro Image Preview)는 Google DeepMind가 출시한 전문가급 AI 이미지 생성 모델입니다. Gemini 3 Pro를 기반으로 구축되었으며, 업계에서는 '정확한 렌더링과 가독성 높은 텍스트를 포함한 이미지를 생성하는 최고의 모델'로 평가받고 있습니다.

Nano Banana Pro 핵심 기술 파라미터

기능 파라미터 설명
텍스트 렌더링 오류율 < 10% 단일 행 텍스트 정확도 업계 최고 수준
출력 해상도 1K / 2K / 4K 후처리 없이 네이티브 고해상도 지원
참조 이미지 최대 14장 다중 이미지 합성 및 캐릭터 일관성 지원
캐릭터 일관성 최대 5명 여러 장면에서 캐릭터 얼굴 일관성 유지
사고 모드 Thinking Process 복잡한 구도 추론 과정 시각화
검색 접지 Google Search 실시간 데이터 기반 시각화 생성

🎯 연결 팁: Nano Banana Pro 공식 서비스는 Google Cloud 해외 신용카드 연동이 필요해 진입 장벽이 높은 편입니다. 대신 APIYI(apiyi.com) 플랫폼을 통한 연결을 추천드려요. 장당 $0.05(공식 4K 가격의 20% 수준)의 단일 가격으로 이용할 수 있으며, 국내 결제 수단을 지원하여 해외 카드 없이도 간편하게 이용 가능합니다.

OpenClaw Skill – Nano Banana Pro 연동을 위한 전체 아키텍처

전체적인 아키텍처를 이해하면 앞으로의 설정을 훨씬 더 수월하게 진행할 수 있어요.

openclaw-nano-banana-pro-image-api-tutorial-ko 图示

왜 APIYI를 통해 연동해야 할까요?

비교 항목 Google 공식 직접 연결 APIYI (apiyi.com) 이용
4K 단가 장당 $0.24 장당 $0.05 (80% 할인)
결제 방식 해외 신용카드 알리페이/위챗페이/USDT
API 형식 Google 네이티브 SDK Gemini 네이티브 형식 호환
네트워크 요구사항 VPN 필요 국내 직접 연결 가능
동시성 제한 할당량(Quota) 제한 있음 동시성 무제한, RPM 2000+
대량 이용 혜택 없음 충전 시 최대 20% 추가 증정

1단계: OpenClaw Skill 디렉토리 구조 생성하기

# Skill 디렉토리 구조 생성
mkdir -p ~/.openclaw/skills/nano-banana-pro/scripts
cd ~/.openclaw/skills/nano-banana-pro
touch SKILL.md scripts/generate.py scripts/edit.py

2단계: SKILL.md 정의 파일 작성하기

SKILL.md는 OpenClaw가 여러분의 스킬(Skill)을 인식하고 호출하는 데 사용하는 핵심 파일이에요. 이 파일은 YAML 프런트 매터(Front Matter)와 Markdown 지침으로 구성됩니다.

---
name: nano-banana-pro
description: Generate and edit images using Nano Banana Pro (Gemini 3 Pro Image) via APIYI platform. Supports text-to-image, image editing, multi-image composition, and batch processing.
version: 1.0.0
metadata:
  openclaw:
    requires:
      env:
        - APIYI_API_KEY
      bins:
        - python3
    primaryEnv: APIYI_API_KEY
emoji: "🎨"
---

Nano Banana Pro 이미지 생성 스킬

주요 기능

  • 텍스트-이미지 변환: 텍스트 설명을 기반으로 고품질 이미지 생성 (1K/2K/4K)
  • 이미지 편집: 기존 이미지 수정, 합성, 스타일 변환
  • 일괄 처리: 이미지 대량 생성 및 일괄 편집 지원

사용 방법

이미지 생성

exec python3 scripts/generate.py --prompt "설명" --aspect-ratio "16:9" --resolution "2K"

이미지 편집

exec python3 scripts/edit.py --instruction "편집 명령" --image-url "이미지 URL"

주의 사항

  • Gemini 네이티브 API 형식을 사용하세요: /v1beta/models/{model}:generateContent
  • 4K 이미지는 약 60초가 소요되므로, exec timeout=120 설정을 권장합니다.
  • 최상의 결과를 위해 영어 프롬프트 사용을 권장합니다.

> 💡 **개발 팁**: `primaryEnv: APIYI_API_KEY`를 선언하면 OpenClaw가 API 키를 Skill 실행 환경에 자동으로 주입합니다. 덕분에 스크립트에서 환경 변수를 통해 직접 읽을 수 있어 키를 하드코딩할 필요가 없습니다.

---


## 세 번째 단계: 텍스트-이미지 변환 스크립트 generate.py 작성하기

이것은 OpenClaw에서 전달된 파라미터를 받아 Nano Banana Pro API를 호출하여 이미지를 생성하는 핵심 스크립트입니다.

### curl 빠른 테스트 (Gemini 네이티브 형식)

먼저 curl 명령어로 API 연결 상태를 확인해 보세요. 가장 빠른 테스트 방법입니다.

```bash
curl -s -X POST \
  "https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "Authorization: Bearer sk-여러분의_APIYI_키" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [
        {"text": "Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme"}
      ]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {
        "aspectRatio": "16:9",
        "imageSize": "2K"
      }
    }
  }' | python3 -c "
import sys, json, base64
data = json.load(sys.stdin)
img_data = data['candidates'][0]['content']['parts'][0]['inlineData']['data']
sys.stdout.buffer.write(base64.b64decode(img_data))
" > gemini-native-image.png

실행에 성공하면 현재 디렉터리에 gemini-native-image.png 파일이 생성됩니다.

Python 스크립트 (Gemini 네이티브 형식)

#!/usr/bin/env python3
"""Nano Banana Pro 텍스트-이미지 변환 스크립트 - OpenClaw Skill (Gemini 네이티브 형식)"""
import os, json, base64, argparse, requests
from datetime import datetime

API_KEY = os.environ.get("APIYI_API_KEY", "")
API_BASE = "https://api.apiyi.com/v1beta/models"  # APIYI Gemini 네이티브 인터페이스

def generate_image(prompt, aspect_ratio="16:9", resolution="2K"):
    url = f"{API_BASE}/gemini-3-pro-image-preview:generateContent"
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }
    data = {
        "contents": [{"parts": [{"text": prompt}]}],
        "generationConfig": {
            "responseModalities": ["IMAGE"],
            "imageConfig": {
                "aspectRatio": aspect_ratio,
                "imageSize": resolution
            }
        }
    }
    response = requests.post(url, headers=headers, json=data, timeout=120)
    response.raise_for_status()
    result = response.json()

    # Gemini 네이티브 형식: candidates에서 inlineData 추출
    parts = result["candidates"][0]["content"]["parts"]
    for part in parts:
        if "inlineData" in part:
            img_bytes = base64.b64decode(part["inlineData"]["data"])
            filename = f"nano_banana_{datetime.now().strftime('%Y%m%d_%H%M%S')}.png"
            with open(filename, "wb") as f:
                f.write(img_bytes)
            print(f"이미지가 생성되었습니다: {filename} ({len(img_bytes)/1024:.1f} KB)")
            return filename
    print("이미지 데이터를 추출하지 못했습니다.")
    return None

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--prompt", required=True)
    parser.add_argument("--aspect-ratio", default="16:9")
    parser.add_argument("--resolution", default="2K", help="해상도: 1K/2K/4K")
    args = parser.parse_args()
    generate_image(args.prompt, args.aspect_ratio, args.resolution)

🚀 빠른 시작: 위 코드는 APIYI(apiyi.com)의 Gemini 네이티브 형식 인터페이스를 사용하며, 엔드포인트는 /v1beta/models/{model}:generateContent입니다. 응답 구조는 Google 공식 API와 완전히 동일합니다. APIYI 콘솔(api.apiyi.com)에서 API 키를 생성하여 바로 시작해 보세요.

4단계: 이미지 편집 스크립트 edit.py 작성하기

Nano Banana Pro는 이미지 생성뿐만 아니라 기존 이미지를 편집하는 기능도 지원해요.

#!/usr/bin/env python3
"""Nano Banana Pro 이미지 편집 스크립트 - OpenClaw Skill (Gemini 네이티브 형식)"""
import os, json, base64, argparse, requests
from datetime import datetime

API_KEY = os.environ.get("APIYI_API_KEY", "")
API_BASE = "https://api.apiyi.com/v1beta/models"

def edit_image(instruction, image_url, extra_images=None):
    url = f"{API_BASE}/gemini-3-pro-image-preview:generateContent"
    headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

    # Gemini 네이티브 형식의 멀티모달 parts 구축
    parts = [{"text": instruction}]
    # 이미지 URL을 base64 인라인 데이터로 변환
    img_resp = requests.get(image_url, timeout=30)
    parts.append({"inlineData": {"mimeType": "image/png",
                                  "data": base64.b64encode(img_resp.content).decode()}})
    if extra_images:  # 다중 이미지 합성 지원 (최대 14장의 참조 이미지)
        for img_url in extra_images[:13]:
            r = requests.get(img_url, timeout=30)
            parts.append({"inlineData": {"mimeType": "image/png",
                                          "data": base64.b64encode(r.content).decode()}})

    data = {
        "contents": [{"parts": parts}],
        "generationConfig": {"responseModalities": ["IMAGE"]}
    }
    response = requests.post(url, headers=headers, json=data, timeout=120)
    response.raise_for_status()
    result_parts = response.json()["candidates"][0]["content"]["parts"]
    for part in result_parts:
        if "inlineData" in part:
            filename = f"edited_{datetime.now().strftime('%Y%m%d_%H%M%S')}.png"
            with open(filename, "wb") as f:
                f.write(base64.b64decode(part["inlineData"]["data"]))
            print(f"편집 완료: {filename}")
            return filename
    return None

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--instruction", required=True)
    parser.add_argument("--image-url", required=True)
    parser.add_argument("--extra-images", nargs="*")
    args = parser.parse_args()
    edit_image(args.instruction, args.image_url, args.extra_images)

이미지 편집 능력 요약

편집 유형 명령 예시 처리 시간
배경 교체 "Remove background and add sunset" ~10초
스타일 변환 "Convert to anime style" ~15초
요소 추가 "Add sunglasses to the person" ~10초
다중 이미지 합성 "Combine these logos and add…" ~20초
텍스트 추가 "Add title text: Hello World" ~10초
색상 조정 "Make the image warmer, increase contrast" ~8초

5단계: OpenClaw 설정 및 테스트

API 키 설정

OpenClaw 설정 파일인 ~/.openclaw/openclaw.json에 Skill 설정을 추가해 주세요.

{
  "skills": {
    "entries": {
      "nano-banana-pro": {
        "enabled": true,
        "apiKey": "sk-여러분의APIYI키"
      }
    }
  }
}

openclaw-nano-banana-pro-image-api-tutorial-ko 图示

Skill 테스트하기

메시지 플랫폼에서 테스트 명령을 보내 기능을 확인해 보세요.

현대적이고 미니멀한 스타일의 이커머스 제품 전시 이미지를 생성해줘. 배경은 흰색, 제품은 중앙에 배치해줘.

Skill이 올바르게 로드되었는지 확인하려면 다음 명령어를 사용하세요.

openclaw skills list | grep nano-banana
openclaw skills test nano-banana-pro

💰 비용 최적화: Nano Banana Pro는 APIYI(apiyi.com)의 단일 요금제를 통해 해상도에 관계없이 장당 $0.05에 이용 가능해요. 프로젝트의 일일 평균 소모량이 5,000장을 넘을 경우, 최대 20%의 충전 보너스 혜택을 받아 장당 비용을 $0.04까지 낮출 수 있습니다.

Nano Banana Pro API 비용 및 성능 비교

장기적인 사용을 위해서는 적절한 접속 방식을 선택하는 것이 매우 중요합니다.

openclaw-nano-banana-pro-image-api-tutorial-ko 图示

위의 SVG 차트에서 상세한 가격 비교와 성능 파라미터를 확인하실 수 있습니다. 주요 수치를 살펴보면, APIYI를 통해 Nano Banana Pro를 사용할 경우 4K 이미지 한 장당 비용은 $0.05로, 공식 가격($0.24)의 20% 수준입니다. 대량 사용 시 충전 보너스를 활용하면 장당 최저 $0.04까지 낮아지기도 하죠. 현재 플랫폼은 일일 10만 장 이상의 이미지를 처리하고 있으며, 동시 요청 수 제한 없이 쾌적하게 이용 가능합니다.

자주 묻는 질문

Q1: OpenClaw에서 Nano Banana Pro를 사용하려면 어떤 의존성 패키지를 설치해야 하나요?

Python 3와 requests 라이브러리만 있으면 됩니다. APIYI(apiyi.com)의 Gemini 네이티브 형식 인터페이스(/v1beta/models/{model}:generateContent)를 통해 모델 호출을 진행하므로, 구글의 google-generativeai SDK를 설치할 필요가 없습니다. pip install requests 명령어로 설치하세요. 별도의 의존성 없이 curl 명령어로 직접 테스트할 수도 있습니다.

Q2: 4K 이미지를 생성할 때 OpenClaw에서 타임아웃 오류가 발생하면 어떻게 하나요?

Nano Banana Pro로 4K 이미지를 생성하는 데는 약 60초가 소요됩니다. SKILL.md의 사용 설명서에서 OpenClaw가 스크립트를 호출할 때 exec timeout=120 또는 exec timeout=180 설정을 사용하도록 권장합니다. 이렇게 하면 기본 타임아웃으로 인해 작업이 중단되는 것을 방지할 수 있습니다.

Q3: Nano Banana Pro 대신 다른 이미지 생성 모델을 사용할 수 있나요?

네, 가능합니다. APIYI(apiyi.com) 플랫폼은 다양한 이미지 생성 모델을 동시에 지원합니다. generate.py 파일에서 model 파라미터만 수정하면 바로 교체할 수 있으며, API 형식이 동일하므로 다른 코드를 수정할 필요가 없습니다.

Q4: OpenClaw Skill의 보안은 어떻게 확보하나요?

세 가지 핵심 조치가 있습니다. 첫째, API 키는 스크립트에 직접 적지 말고 환경 변수를 통해 주입하세요. 둘째, 직접 만든 Skill만 사용하세요. ClawHub에서 출처가 불분명한 이미지 생성 스킬을 설치하는 것은 피해야 합니다(이미 820개 이상의 악성 스킬이 발견되었습니다). 셋째, 정기적으로 OpenClaw 로그를 확인하여 이상 호출이 없는지 점검하세요.

Q5: 이미지 편집은 어떤 기능을 지원하며 성능은 어떤가요?

Nano Banana Pro는 배경 교체, 스타일 변환, 요소 추가/삭제, 다중 이미지 합성(최대 14장의 참조 이미지 사용), 텍스트 렌더링 등을 지원합니다. 특히 텍스트 렌더링은 DALL-E 3나 Midjourney를 훨씬 능가하는 성능을 보여주며, 단일 행 텍스트 오류율이 10% 미만입니다. APIYI 플랫폼을 통해 편집 기능을 호출하면 회당 단 $0.05의 비용으로 평균 10초 내에 완료됩니다.

요약

이 튜토리얼의 5단계를 통해 OpenClaw를 위한 커스텀 Skill을 만들고 Nano Banana Pro 이미지 API를 연동하는 전체 과정을 살펴보았습니다:

  1. Skill 디렉토리 생성 — 표준 SKILL.md + scripts/ 구조 구성
  2. SKILL.md 작성 — 의존성, 환경 변수 및 사용 지침 선언
  3. 텍스트-이미지 변환 스크립트 작성 — APIYI의 Gemini 네이티브 형식 인터페이스를 통한 Nano Banana Pro 호출
  4. 편집 스크립트 작성 — 다중 이미지 합성, 배경 교체, 스타일 변환 지원
  5. 설정 및 테스트 — openclaw.json에 키 설정 및 기능 검증

APIYI(apiyi.com)를 통해 Nano Banana Pro를 연동하면 장당 $0.05라는 합리적인 가격(공식 4K 가격의 20% 수준)으로 이용할 수 있습니다. Claude, GPT-4o, DeepSeek 등 다양한 모델을 통합 인터페이스로 지원하며, imagen.apiyi.com에서 무료로 이미지 생성 효과를 체험해 볼 수 있습니다.

본 문서는 APIYI 기술 팀에서 작성하였으며, AI 대규모 언어 모델 API 연동 실무와 Agent 개발 튜토리얼을 다룹니다. 더 많은 기술 가이드는 APIYI 도움말 센터(help.apiyi.com)를 방문해 주세요.

Try AI Large Model https://api.apiyi.com for free
Stable and reliable AI LM API aggregation service, Get 300 Millions Tokens for Free~

Similar Posts