나노 바나나 프로 API 사용법: 공식 JSON·YAML 설정과 이미지 저장

{
  "model": "gemini-3-pro-image",
  "input": [
    {
      "type": "text",
      "text": "독립 커피 브랜드의 웹사이트 대표 이미지를 만들어 주세요. 무광 검정 커피백 한 개를 중앙에 배치하고 따뜻한 아침 창가광을 사용하세요. 좌우에는 여백을 남기고, 가격이나 새로운 로고는 넣지 마세요."
    }
  ],
  "response_format": {
    "type": "image",
    "mime_type": "image/png",
    "aspect_ratio": "16:9",
    "image_size": "2K"
  },
  "store": false
}

curl --silent --show-error --fail-with-body \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: YOUR_GOOGLE_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json \
  --output interaction-response.json

import base64
import binascii
import json
import sys
from pathlib import Path

EXTENSIONS = {
    "image/png": ".png",
    "image/jpeg": ".jpg",
    "image/webp": ".webp",
}


def save_images(response, destination):
    if not isinstance(response, dict):
        raise ValueError("응답의 최상위 값은 객체여야 합니다.")
    if response.get("error"):
        raise ValueError(f"API 오류: {response['error']}")
    steps = response.get("steps", [])
    if not isinstance(steps, list):
        raise ValueError("steps는 배열이어야 합니다.")

    images = []
    for step in steps:
        if not isinstance(step, dict):
            raise ValueError("단계 값은 객체여야 합니다.")
        if step.get("type") != "model_output":
            continue
        content = step.get("content", [])
        if not isinstance(content, list):
            raise ValueError("content는 배열이어야 합니다.")
        for block in content:
            if not isinstance(block, dict):
                raise ValueError("출력 블록은 객체여야 합니다.")
            if block.get("type") != "image":
                continue
            mime = block.get("mime_type")
            data = block.get("data")
            if not isinstance(mime, str) or mime not in EXTENSIONS:
                raise ValueError(f"처리하지 않은 이미지 MIME: {mime}")
            if not isinstance(data, str) or not data:
                raise ValueError("이미지의 raw base64 데이터가 없습니다.")
            try:
                raw = base64.b64decode(data, validate=True)
            except (binascii.Error, ValueError) as exc:
                raise ValueError("유효하지 않은 base64입니다.") from exc
            if not raw:
                raise ValueError("빈 이미지 데이터입니다.")
            images.append((mime, raw))

    if not images:
        raise ValueError("최종 이미지가 없습니다. 응답과 차단 사유를 확인하세요.")
    target = Path(destination)
    target.mkdir(parents=True, exist_ok=False)
    paths = []
    for index, (mime, raw) in enumerate(images, start=1):
        path = target / f"image-{index:03d}{EXTENSIONS[mime]}"
        path.write_bytes(raw)
        paths.append(str(path))
    return paths


if __name__ == "__main__":
    if len(sys.argv) != 3:
        raise SystemExit("사용법: python save_images.py 응답.json 새출력폴더")
    response = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8"))
    print(json.dumps(save_images(response, sys.argv[2]), ensure_ascii=False))

python save_images.py interaction-response.json output-coffee-001

{
  "provider": "google",
  "api": "interactions",
  "model": "gemini-3-pro-image",
  "brief": "독립 커피 브랜드의 웹사이트 대표 이미지",
  "must_include": ["무광 검정 커피백 한 개", "좌우 여백", "따뜻한 창가광"],
  "avoid": ["가격", "새로운 로고"],
  "references": [],
  "output": {
    "aspect_ratio": "16:9",
    "image_size": "2K",
    "mime_type": "image/png"
  },
  "store": false
}

provider: google
api: interactions
model: gemini-3-pro-image
brief: 독립 커피 브랜드의 웹사이트 대표 이미지
must_include:
  - 무광 검정 커피백 한 개
  - 좌우 여백
  - 따뜻한 창가광
avoid:
  - 가격
  - 새로운 로고
references: []
output:
  aspect_ratio: "16:9"
  image_size: "2K"
  mime_type: image/png
store: false

import base64
import json
import sys
from pathlib import Path

RATIOS = {
    "1:1", "2:3", "3:2", "3:4", "4:3",
    "4:5", "5:4", "9:16", "16:9", "21:9",
}
SIZES = {"1K", "2K", "4K"}
MIMES = {"image/png", "image/jpeg", "image/webp"}
FIELDS = {
    "provider", "api", "model", "brief", "must_include",
    "avoid", "references", "output", "store",
}


def text(value, name):
    if not isinstance(value, str) or not value.strip():
        raise ValueError(f"{name}: 비어 있지 않은 문자열이 필요합니다.")
    return value.strip()


def strings(value, name):
    if not isinstance(value, list):
        raise ValueError(f"{name}: 문자열 배열이 필요합니다.")
    return [text(item, name) for item in value]


def build_request(spec, base_dir):
    if not isinstance(spec, dict) or set(spec) != FIELDS:
        raise ValueError("앱 설정의 필드가 예시 스키마와 다릅니다.")
    if (spec["provider"], spec["api"], spec["model"]) != (
        "google", "interactions", "gemini-3-pro-image"
    ):
        raise ValueError("이 변환기는 Google Interactions Pro 전용입니다.")
    if type(spec["store"]) is not bool:
        raise ValueError("store는 true 또는 false 불리언이어야 합니다.")
    output = spec["output"]
    if not isinstance(output, dict) or set(output) != {
        "aspect_ratio", "image_size", "mime_type"
    }:
        raise ValueError("output 필드가 올바르지 않습니다.")
    ratio = text(output["aspect_ratio"], "aspect_ratio")
    size = text(output["image_size"], "image_size")
    mime = text(output["mime_type"], "mime_type")
    if ratio not in RATIOS or size not in SIZES or mime not in MIMES:
        raise ValueError("지원 목록 밖의 비율·해상도·MIME입니다.")

    prompt = " ".join([
        text(spec["brief"], "brief") + ".",
        "포함할 요소: " + ", ".join(strings(spec["must_include"], "must_include")) + ".",
        "넣지 않을 요소: " + ", ".join(strings(spec["avoid"], "avoid")) + ".",
    ])
    references = spec["references"]
    if not isinstance(references, list) or len(references) > 14:
        raise ValueError("references는 최대 14개인 배열이어야 합니다.")
    parts = [{"type": "text", "text": prompt}]
    for reference in references:
        if not isinstance(reference, dict) or set(reference) != {"path", "mime_type"}:
            raise ValueError("참조 이미지에는 path와 mime_type이 필요합니다.")
        image_mime = text(reference["mime_type"], "참조 MIME")
        if image_mime not in MIMES:
            raise ValueError("참조 이미지 MIME을 확인하세요.")
        path = Path(text(reference["path"], "참조 파일"))
        if not path.is_absolute():
            path = Path(base_dir) / path
        raw = path.read_bytes()
        if not raw:
            raise ValueError("참조 이미지가 비어 있습니다.")
        parts.append({
            "type": "image",
            "mime_type": image_mime,
            "data": base64.b64encode(raw).decode("ascii"),
        })
    return {
        "model": spec["model"],
        "input": parts,
        "response_format": {
            "type": "image", "mime_type": mime,
            "aspect_ratio": ratio, "image_size": size,
        },
        "store": spec["store"],
    }


def load_spec(path):
    source = path.read_text(encoding="utf-8")
    if path.suffix.lower() == ".json":
        return json.loads(source)
    if path.suffix.lower() in {".yaml", ".yml"}:
        try:
            import yaml
        except ImportError as exc:
            raise RuntimeError("YAML 읽기에는 PyYAML이 필요합니다.") from exc
        return yaml.safe_load(source)
    raise ValueError("설정 파일은 JSON 또는 YAML이어야 합니다.")


if __name__ == "__main__":
    if len(sys.argv) != 3:
        raise SystemExit("사용법: python build_request.py 설정파일 요청.json")
    source_path = Path(sys.argv[1])
    request = build_request(load_spec(source_path), source_path.parent)
    Path(sys.argv[2]).write_text(
        json.dumps(request, ensure_ascii=False, indent=2), encoding="utf-8"
    )

python build_request.py spec.json request.json
# 같은 설정을 spec.yaml로 저장하고 PyYAML을 준비한 환경이라면:
python build_request.py spec.yaml request-from-yaml.json

import base64
import json
import sys
from pathlib import Path

if len(sys.argv) != 3:
    raise SystemExit("사용법: python prepare_pdf.py 문서.pdf pdf-request.json")
source = Path(sys.argv[1])
raw = source.read_bytes()
if not raw.startswith(b"%PDF-"):
    raise ValueError("PDF 파일을 준비하세요.")
request = {
    "model": "gemini-3.8-flash",
    "input": [
        {"type": "document", "mime_type": "application/pdf",
         "data": base64.b64encode(raw).decode("ascii")},
        {"type": "text", "text": (
            "제품 소개 이미지에 필요한 사실만 추출하세요. "
            "각 사실의 원문과 PDF 페이지 번호를 함께 적고, "
            "명시되지 않은 내용은 추측하지 마세요. "
            "브랜드명, 제품명, 색상 규칙, 금지 표현을 구분하세요."
        )},
    ],
    "store": False,
}
Path(sys.argv[2]).write_text(
    json.dumps(request, ensure_ascii=False, indent=2), encoding="utf-8"
)

python prepare_pdf.py catalog.pdf pdf-request.json

curl --silent --show-error --fail-with-body \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: YOUR_GOOGLE_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @pdf-request.json \
  --output pdf-response.json

{
  "source_file": "catalog.pdf",
  "verified": true,
  "facts": [
    {"page": 1, "text": "제품명: 새벽 블렌드"},
    {"page": 12, "text": "포장색: 무광 검정"}
  ],
  "reference_images": []
}

import json
import sys
from pathlib import Path
from build_request import build_request, strings, text

if len(sys.argv) != 3:
    raise SystemExit("사용법: python handoff_to_spec.py 인계.json 요청.json")
source = Path(sys.argv[1])
handoff = json.loads(source.read_text(encoding="utf-8"))
if not isinstance(handoff, dict) or set(handoff) != {
    "source_file", "verified", "facts", "reference_images"
}:
    raise ValueError("인계 파일의 필드를 확인하세요.")
text(handoff["source_file"], "PDF 출처")
if handoff["verified"] is not True:
    raise ValueError("원문 검토를 먼저 완료하세요.")
if not isinstance(handoff["facts"], list) or not handoff["facts"]:
    raise ValueError("검토된 사실 목록이 필요합니다.")
facts = []
for item in handoff["facts"]:
    if not isinstance(item, dict) or set(item) != {"page", "text"}:
        raise ValueError("각 사실에는 page와 text가 필요합니다.")
    if type(item["page"]) is not int or item["page"] < 1:
        raise ValueError("페이지 번호는 1 이상의 정수여야 합니다.")
    facts.append(text(item["text"], "검토된 사실"))
spec = {
    "provider": "google", "api": "interactions",
    "model": "gemini-3-pro-image",
    "brief": "검토된 제품 정보로 웹사이트 대표 이미지를 만들어 주세요",
    "must_include": strings(facts, "사실 목록"),
    "avoid": ["자료에 없는 효능", "새로운 가격", "추가 로고"],
    "references": handoff["reference_images"],
    "output": {"aspect_ratio": "16:9", "image_size": "2K", "mime_type": "image/png"},
    "store": False,
}
request = build_request(spec, source.parent)
Path(sys.argv[2]).write_text(
    json.dumps(request, ensure_ascii=False, indent=2), encoding="utf-8"
)

python handoff_to_spec.py verified-facts.json request.json