Nano Banana Pro API 怎么调用：JSON 请求、YAML 配置与 PDF 转图

{
  "model": "gemini-3-pro-image",
  "input": [
    {
      "type": "text",
      "text": "为一家茶饮店制作夏季新品海报。主体是一杯透明杯青柠气泡茶，浅绿色背景，产品居中。画面只出现“青柠气泡茶”和“夏日限定”两组中文。不要价格、人物、英文副标题或额外 Logo。"
    }
  ],
  "response_format": {
    "type": "image",
    "mime_type": "image/png",
    "aspect_ratio": "16:9",
    "image_size": "2K"
  },
  "store": false
}

curl --fail-with-body -sS -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" -H "x-goog-api-key: $GEMINI_API_KEY" -H "Content-Type: application/json" --data-binary @request.json -o response.json

import base64
import json
import sys
from pathlib import Path

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

def outputs(response, mode):
    if mode == "interactions":
        for step_index, step in enumerate(response.get("steps", [])):
            if step.get("type") != "model_output":
                continue
            for part_index, part in enumerate(step.get("content", [])):
                yield f"{step_index}-{part_index}", part
    elif mode == "generateContent":
        for candidate_index, candidate in enumerate(
            response.get("candidates", [])
        ):
            for part_index, part in enumerate(
                candidate.get("content", {}).get("parts", [])
            ):
                if part.get("thought") is True:
                    continue
                if "inlineData" in part:
                    item = part["inlineData"]
                    yield f"{candidate_index}-{part_index}", {
                        "type": "image",
                        "mime_type": item.get("mimeType"),
                        "data": item.get("data"),
                    }
                elif "text" in part:
                    yield f"{candidate_index}-{part_index}", {
                        "type": "text", "text": part["text"]
                    }
    else:
        raise ValueError("模式只能是 interactions 或 generateContent")

def save(response_file, output_dir, mode):
    raw = Path(response_file).read_bytes()
    response = json.loads(raw)
    folder = Path(output_dir)
    folder.mkdir(parents=True, exist_ok=False)
    (folder / "response.json").write_bytes(raw)
    if response.get("error"):
        raise RuntimeError(json.dumps(response["error"], ensure_ascii=False))
    images, texts = [], []
    for index, part in outputs(response, mode):
        if part.get("type") == "text":
            texts.append(part.get("text", ""))
        elif part.get("type") == "image":
            mime = part.get("mime_type")
            if mime not in EXTENSIONS:
                raise ValueError(f"未处理的图片 MIME：{mime}")
            data = part.get("data")
            if not isinstance(data, str) or not data:
                raise ValueError("图片缺少内联 base64，需按实际响应另行处理")
            image_bytes = base64.b64decode(data, validate=True)
            if not image_bytes:
                raise ValueError("图片字节为空")
            filename = f"image-{index}{EXTENSIONS[mime]}"
            (folder / filename).write_bytes(image_bytes)
            images.append({"file": filename, "mime_type": mime})
    (folder / "text.txt").write_text(
        chr(10).join(texts), encoding="utf-8"
    )
    (folder / "manifest.json").write_text(
        json.dumps({"images": images}, ensure_ascii=False, indent=2),
        encoding="utf-8",
    )
    if not images:
        raise RuntimeError("没有最终图片；原始响应和文字已保存，请检查原因")
    return images

if __name__ == "__main__":
    if len(sys.argv) != 4:
        raise SystemExit(
            "用法：python3 save_images.py 响应.json 新输出目录 模式"
        )
    print(json.dumps(save(*sys.argv[1:]), ensure_ascii=False))

python3 save_images.py response.json result-001 interactions

{
  "route": "google-interactions",
  "model": "gemini-3-pro-image",
  "creative": {
    "subject": "透明杯青柠气泡茶",
    "required_text": ["青柠气泡茶", "夏日限定"],
    "visual_rules": ["浅绿色背景", "产品居中", "杯身完整可见"],
    "forbidden": ["价格", "人物", "英文副标题", "额外 Logo"]
  },
  "output": {
    "aspect_ratio": "16:9",
    "image_size": "2K"
  },
  "reference_images": []
}

route: google-interactions
model: gemini-3-pro-image
creative:
  subject: 透明杯青柠气泡茶
  required_text:
    - 青柠气泡茶
    - 夏日限定
  visual_rules:
    - 浅绿色背景
    - 产品居中
    - 杯身完整可见
  forbidden:
    - 价格
    - 人物
    - 英文副标题
    - 额外 Logo
output:
  aspect_ratio: "16:9"
  image_size: "2K"
reference_images: []

import base64
import json
import sys
from pathlib import Path
from typing import TypedDict

class Creative(TypedDict):
    subject: str
    required_text: list[str]
    visual_rules: list[str]
    forbidden: list[str]

class Output(TypedDict):
    aspect_ratio: str
    image_size: str

class AppConfig(TypedDict):
    route: str
    model: str
    creative: Creative
    output: Output
    reference_images: list[str]

RATIOS = {
    "1:1", "2:3", "3:2", "3:4", "4:3",
    "4:5", "5:4", "9:16", "16:9", "21:9",
}

def exact_keys(value, names, label):
    if not isinstance(value, dict) or set(value) != set(names):
        raise ValueError(f"{label} 必须且只能包含：{names}")

def string(value, label):
    if not isinstance(value, str) or not value.strip():
        raise ValueError(f"{label} 必须是非空字符串")
    return value

def strings(value, label):
    if not isinstance(value, list):
        raise ValueError(f"{label} 必须是字符串数组")
    return [string(item, label) for item in value]

def image_part(filename):
    raw = Path(filename).read_bytes()
    if raw.startswith(bytes([137, 80, 78, 71, 13, 10, 26, 10])):
        mime = "image/png"
    elif raw.startswith(bytes([255, 216, 255])):
        mime = "image/jpeg"
    elif raw[:4] == b"RIFF" and raw[8:12] == b"WEBP":
        mime = "image/webp"
    else:
        raise ValueError(f"参考图不是可识别的 PNG/JPEG/WebP：{filename}")
    return {
        "type": "image", "mime_type": mime,
        "data": base64.b64encode(raw).decode("ascii"),
    }

def compile_config(config: AppConfig):
    exact_keys(config, [
        "route", "model", "creative", "output", "reference_images"
    ], "应用配置")
    if config["route"] != "google-interactions":
        raise ValueError("此转换器仅支持 Google Interactions")
    if config["model"] != "gemini-3-pro-image":
        raise ValueError("此转换器仅针对 Pro 模型")
    creative = config["creative"]
    exact_keys(creative, [
        "subject", "required_text", "visual_rules", "forbidden"
    ], "creative")
    subject = string(creative["subject"], "subject")
    required = strings(creative["required_text"], "required_text")
    rules = strings(creative["visual_rules"], "visual_rules")
    forbidden = strings(creative["forbidden"], "forbidden")
    output = config["output"]
    exact_keys(output, ["aspect_ratio", "image_size"], "output")
    ratio = string(output["aspect_ratio"], "aspect_ratio")
    size = string(output["image_size"], "image_size")
    if ratio not in RATIOS or size not in {"1K", "2K", "4K"}:
        raise ValueError("比例或尺寸不在此 Pro 配置支持范围")
    references = strings(config["reference_images"], "reference_images")
    if len(references) > 14:
        raise ValueError("参考图总数超过 14")
    lines = [f"制作海报，主体：{subject}。"]
    if required:
        lines.append("必须出现且准确拼写的文字：" + "、".join(required))
    if rules:
        lines.append("构图要求：" + "；".join(rules))
    if forbidden:
        lines.append("不要出现：" + "、".join(forbidden))
    parts = [{"type": "text", "text": chr(10).join(lines)}]
    parts.extend(image_part(path) for path in references)
    return {
        "model": config["model"],
        "input": parts,
        "response_format": {
            "type": "image", "mime_type": "image/png",
            "aspect_ratio": ratio, "image_size": size,
        },
        "store": False,
    }

def load_config(filename):
    path = Path(filename)
    text = path.read_text(encoding="utf-8")
    if path.suffix.lower() == ".json":
        return json.loads(text)
    if path.suffix.lower() in {".yaml", ".yml"}:
        try:
            import yaml
        except ImportError as error:
            raise RuntimeError("YAML 读取需要 PyYAML；也可以使用 JSON") from error
        return yaml.safe_load(text)
    raise ValueError("输入文件应为 .json、.yaml 或 .yml")

if __name__ == "__main__":
    if len(sys.argv) != 3:
        raise SystemExit("用法：python3 compile_request.py 配置文件 请求.json")
    result = compile_config(load_config(sys.argv[1]))
    Path(sys.argv[2]).write_text(
        json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8"
    )

python3 compile_request.py creative.json request.json
python3 compile_request.py creative.yaml request.json

import base64
import json
import sys
from pathlib import Path
from compile_request import compile_config, exact_keys, string

def write_json(filename, value):
    Path(filename).write_text(
        json.dumps(value, ensure_ascii=False, indent=2), encoding="utf-8"
    )

def pdf_request(source, destination):
    raw = Path(source).read_bytes()
    if not raw.startswith(b"%PDF-") or len(raw) > 50_000_000:
        raise ValueError("需要 PDF 文件，且此示例限定为不超过 50 MB")
    instruction = (
        "从报告中提取用于中文数据海报的事实。请返回一个 JSON 对象，"
        "包含 facts 数组，每项有 label、value、unit、page_refs、quote。"
        "page_refs 使用从 1 开始的 PDF 页码整数数组；"
        "quote 保留支持数值的原文。没有依据的字段不要补造。"
        "只返回 JSON，不要 Markdown 围栏。"
    )
    write_json(destination, {
        "model": "gemini-3.8-flash",
        "input": [
            {"type": "text", "text": instruction},
            {
                "type": "document", "mime_type": "application/pdf",
                "data": base64.b64encode(raw).decode("ascii"),
            },
        ],
        "store": False,
    })

def extracted_text(response_file, destination):
    response = json.loads(Path(response_file).read_text(encoding="utf-8"))
    if response.get("error"):
        raise ValueError("文档请求失败，请先检查原始响应")
    texts = [
        part["text"]
        for step in response.get("steps", [])
        if step.get("type") == "model_output"
        for part in step.get("content", [])
        if part.get("type") == "text" and isinstance(part.get("text"), str)
    ]
    if not texts:
        raise ValueError("文档响应没有最终文字")
    Path(destination).write_text(chr(10).join(texts), encoding="utf-8")

def handoff(source, destination):
    value = json.loads(Path(source).read_text(encoding="utf-8"))
    exact_keys(value, ["verified", "subject", "facts", "page_images"], "核对文件")
    if value["verified"] is not True:
        raise ValueError("先核对 PDF 原文，再明确标记 verified 为 true")
    if not isinstance(value["facts"], list) or not value["facts"]:
        raise ValueError("至少需要一项已核对事实")
    required, provenance = [], []
    for fact in value["facts"]:
        exact_keys(fact, ["label", "value", "unit", "page_refs", "quote"], "事实")
        label = string(fact["label"], "label")
        number = string(fact["value"], "value")
        unit = string(fact["unit"], "unit")
        quote = string(fact["quote"], "quote")
        pages = fact["page_refs"]
        if not isinstance(pages, list) or not pages or any(
            type(page) is not int or page < 1 for page in pages
        ):
            raise ValueError("page_refs 必须是非空正整数数组")
        required.append(f"{label}：{number}{unit}")
        provenance.append({
            "label": label, "page_refs": pages, "quote": quote
        })
    config = {
        "route": "google-interactions", "model": "gemini-3-pro-image",
        "creative": {
            "subject": string(value["subject"], "subject"),
            "required_text": required,
            "visual_rules": ["信息层级清楚", "数字和单位成组显示"],
            "forbidden": ["未提供的数字", "虚构来源", "额外统计结论"],
        },
        "output": {"aspect_ratio": "16:9", "image_size": "2K"},
        "reference_images": value["page_images"],
    }
    request = compile_config(config)
    write_json(destination, request)
    write_json(str(destination) + ".facts.json", provenance)

if __name__ == "__main__":
    actions = {
        "pdf-request": pdf_request,
        "extract-text": extracted_text,
        "handoff": handoff,
    }
    if len(sys.argv) != 4 or sys.argv[1] not in actions:
        raise SystemExit(
            "用法：python3 pdf_workflow.py "
            "pdf-request|extract-text|handoff 输入文件 输出文件"
        )
    actions[sys.argv[1]](*sys.argv[2:])

python3 pdf_workflow.py pdf-request report.pdf document-request.json

curl --fail-with-body -sS -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" -H "x-goog-api-key: $GEMINI_API_KEY" -H "Content-Type: application/json" --data-binary @document-request.json -o document-response.json
python3 pdf_workflow.py extract-text document-response.json extracted.txt

{
  "verified": true,
  "subject": "某茶饮门店季度经营数据海报",
  "facts": [
    {
      "label": "季度营收同比增长",
      "value": "18.6",
      "unit": "%",
      "page_refs": [3],
      "quote": "合成示例：本季度营收同比增长 18.6%。"
    }
  ],
  "page_images": []
}

python3 pdf_workflow.py handoff verified.json request.json

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {"text": "生成青柠气泡茶海报，只出现“青柠气泡茶”和“夏日限定”，浅绿色背景，产品居中。"}
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": ["TEXT", "IMAGE"],
    "imageConfig": {
      "aspectRatio": "16:9",
      "imageSize": "2K"
    }
  }
}

curl --fail-with-body -sS -X POST "https://api.laozhang.ai/v1beta/models/gemini-3-pro-image:generateContent" -H "Authorization: Bearer $LAOZHANG_API_KEY" -H "Content-Type: application/json" --data-binary @provider-request.json -o provider-response.json
python3 save_images.py provider-response.json provider-result-001 generateContent