nano-banana-image-ad

nano-banana-image-ad（Arcads）

通过 Arcads 的 POST /v2/images/generate 和 Nano Banana 系列模型（默认为 nano-banana-2）生成一个或多个独立的 Meta 广告图片创意。生成的图片路径会交给 Meta-ad-builder 技能——此技能本身不会上传图片到 Meta。

阅读顺序

1. 本文件 — Arcads 专属的端点、身份验证、预签名上传流程和工作流阶段。
2. shared/skills/nano-banana-image-ad/prompting/guide.md — 特定于模型的提示词编写指南（Nano Banana 擅长和不擅长什么，以及何时切换到 gpt-image-2）。
3. shared/skills/image-ad-prompting/prompting/prompt-library.md — 30 多个经过验证的模板，附带针对各模型的说明。
4. shared/skills/image-ad-prompting/prompting/safety-suffixes.md — 始终启用的 3 项防护措施。
5. scripts/generate_image.py — 辅助脚本（仅使用 Python 标准库）。

硬性规则——绝不可放宽

1. 模型必须属于 Nano Banana 系列。 脚本接受 nano-banana-2（默认）、nano-banana-pro（Gemini 3 Pro Image，成本更高／可锁定身份）、nano-banana-edit（专注于局部重绘）或 nano-banana（旧版）。其他模型一律拒绝。如果用户要求使用 gpt-image-2，请引导他们使用 chatgpt-image-ad。
2. 输出中不得包含平台／截图界面元素。 NO_CHROME_SUFFIX 始终启用（仅可通过 --allow-chrome 覆盖）。
3. 始终启用边缘安全和字形安全后缀，除非明确指定 --no-safe-zone。
4. 参考图片最多 14 张。 这是 Nano Banana 在 Arcads 中的硬性上限。脚本会强制执行。
5. 此技能不会上传图片到 Meta。 仅生成图片。用户的工具栈中有单独的广告制作技能——通过文件系统路径移交。
6. 生成前务必提供预计的积分成本。 每次 Nano Banana 调用生成一张图片；乘以 --n 即可计算总数。nano-banana-pro 的成本高于 nano-banana-2——应从 logs/arcads-api.jsonl 中查询并说明各模型的费率。

前置条件

• .env 中包含 ARCADS_BASIC_AUTH（优先）或 ARCADS_API_KEY
• 可选：在 .env 中设置 PRODUCT_ID、PROJECT_ID，用于整理会话文件夹
• 本地磁盘上的参考图片。脚本会在内部处理 Arcads 预签名上传流程。

配置

• 基础 URL： https://external-api.arcads.ai（或 ARCADS_BASE_URL）。
• 身份验证： HTTP Basic。脚本优先使用预编码的 ARCADS_BASIC_AUTH；若无，则对 ARCADS_API_KEY 进行编码。
• 端点： POST /v2/images/generate；轮询 GET /v1/assets/{id}，直到 status: generated。
• 参考图片上传： POST /v1/file-upload/get-presigned-url 返回 {presignedUrl, filePath}；将字节数据 PUT 到 presignedUrl；在 referenceImages 中传入 filePath。链接只能使用一次——脚本会为每个变体重新上传。

生成模式

模式	适用场景	必需参数	可选参数
image（默认）	全新广告图片。	--prompt、--aspect-ratio	--image-ref（最多 14 张）
image_edit	修改 --source 图片。	--prompt、--source	--image-ref（最多 14 张）

支持的宽高比

1:1、16:9、9:16。Arcads 的 /v2/images/generate 端点只接受这三种宽高比（gpt-image-2 和 Nano Banana 共用此端点，因此宽高比限制相同）。共享模板库中使用 2:3、4:5、3:2 等宽高比的模板，无法在此后端以原生比例生成——请改用 1:1 并在生成后裁剪，或者使用 KIE nano-banana-image-ad 同系列技能；它通过 /jobs/createTask 端点原生支持完整的 Meta 宽高比集合。

模型变体（--model）

• nano-banana-2（默认）— Gemini 2.5 Flash Image。标准选项。适用于大多数模板。
• nano-banana-pro — Gemini 3 Pro Image。适用于主视觉静帧、跨多次运行保持角色一致性，以及对材质真实感要求高的镜头（黏土动画、Pixar、高端产品摄影）。消耗更多积分。
• nano-banana-edit — 专注于局部重绘。仅在使用 --mode image_edit 进行精确蒙版编辑时使用（替换背景、更改物体颜色）。
• nano-banana — 旧版。仅在用户明确要求时使用；新任务应使用 nano-banana-2。

如果 MASTER_CONTEXT.md 中尚未设置模型变体，请在会话中首次生成前询问用户要使用哪种变体。默认使用 nano-banana-2。

工作流

阶段 1：预检

1. .env 文件存在且包含凭据。
2. （可选）已设置 arcads-external-api 会话文件夹。
3. 健康检查：curl -sf -H "$AUTH" "$BASE_URL/v1/products" 返回 200。

阶段 2：收集输入

收集：种子提示词、模式、来源（如为编辑）、参考路径（最多 14 个）、变体数量、宽高比、模型变体。

阶段 3：重写提示词

阅读 shared/skills/image-ad-prompting/prompting/prompt-library.md。如果用户的需求符合某个模板，检查 Model notes 区块——只有在 nano-banana 标记为干净、首选或强时才继续。如果首选的是 gpt-image-2，建议切换技能。

填入 {placeholders} 并向用户展示重写后的提示词。生成前征求用户批准。

对于新提示词（不匹配任何模板），遵循 shared/skills/nano-banana-image-ad/prompting/guide.md § Phase 3b 中的结构——充分利用 Nano Banana 的优势（指定参考图角色、明确光照细节、明确材质细节）。

阶段 4：确认积分成本（必须）

展示预估积分成本（从 logs/arcads-api.jsonl 中匹配的历史调用记录读取）。醒目注明模型变体：nano-banana-pro 的成本高于 nano-banana-2。等待用户明确确认。

阶段 5：生成

~/.claude/skills/nano-banana-image-ad/scripts/generate_image.py \
  --prompt "<rewritten>" \
  --aspect-ratio <ratio> \
  --n <N> \
  --image-ref <product.png> \
  [--image-ref <character.png>] \
  [--image-ref <style.png>] \
  --out ./generated \
  --env-file .env

# For higher-stakes hero shots:
~/.claude/skills/nano-banana-image-ad/scripts/generate_image.py \
  --model nano-banana-pro \
  --prompt "<rewritten>" \
  --aspect-ratio <ratio> \
  --n <N> \
  --image-ref <product.png> \
  --out ./generated \
  --env-file .env

# For an edit run (inpaint):
~/.claude/skills/nano-banana-image-ad/scripts/generate_image.py \
  --mode image_edit \
  --model nano-banana-edit \
  --prompt "<edit-instruction>" \
  --source <existing.png> \
  [--image-ref <guidance.png>] \
  --n <N> \
  --out ./generated \
  --env-file .env

stdout 中的每一行都是一个 JSON 变体（variant、path、asset_id、width、height、prompt、mode、aspect_ratio、model）。

将每次调用记录到 logs/arcads-api.jsonl，包括模型变体、参考图数量和返回的 asset_id。

阶段 6：视觉质检（必须）

对于每个已完成的变体，读取图像并检查以下问题：

• 小字乱码（Nano Banana 的主要弱点）
• 多余手指／肢体数量错误（Gemini 系列常见问题）
• 品牌字标偏移（始终通过 --image-ref 提供品牌字标，以减轻此问题）
• 不同变体之间的角色身份偏移（如果身份一致性很重要，使用 nano-banana-pro 锁定身份）

如果存在缺陷：使用明确指出要修正问题的改写提示词重新生成（参见 shared/skills/nano-banana-image-ad/prompting/guide.md § Retry mode）。每个变体最多重试 2 次。

阶段 7：确认并交接

向用户展示所有路径。询问“全部使用／使用指定项／重新生成／取消”。

所选变体已可交由你的 Meta-ad-builder skill 使用。输出这些路径。

也可以将所选路径写入 ./generated/run-<ts>.jsonl，供下游使用。

不在范围内——明确拒绝

• Meta 上传 — 使用你工具栈中的其他技能。
• ChatGPT Image 2 / gpt-image-2 生成 — 使用 chatgpt-image-ad。
• 视频、轮播广告、DCO 广告 — 仅支持图像。
• 广告文案撰写 — 使用其他技能。
• 编辑共享提示词库 — 使用 image-ad-clone（在阶段 1 询问使用哪个后端）。

常见错误

• 401/403 → 修复 .env。
• 422 validation/moderation → 收紧提示词；检查 aspectRatio 是否在支持范围内；检查 --n ≤ 5。
• 500 UNKNOWN_ERROR → 通常是预签名 filePath 已过期。脚本会为每个变体重新上传；如果问题持续存在，请使用 asset_id 提交问题报告。

此技能包含的文件

• ~/.claude/skills/nano-banana-image-ad/SKILL.md — 此文件
• ~/.claude/skills/nano-banana-image-ad/scripts/generate_image.py — Arcads Nano Banana 调用程序

另请参阅

• shared/skills/nano-banana-image-ad/prompting/guide.md — 特定于模型的提示词编写
• shared/skills/image-ad-prompting/prompting/prompt-library.md — 共享模板库
• image-ad-clone skill — 与后端无关的独立技能，可对现有广告进行逆向分析，并将其转化为可复用的库条目
• arcads-external-api skill — 底层 Arcads 规范
• chatgpt-image-ad skill — 用于排版密集型／UI 仿制模板的同类技能