chatgpt-image-ad

chatgpt-image-ad (Arcads)

通过 Arcads 的 POST /v2/images/generate 和 model: "gpt-image-2" 生成一个或多个独立的 Meta 广告图片创意。将图片路径交给你的 Meta 广告制作技能——此技能本身不会上传到 Meta。

阅读顺序

1. 本文件 — Arcads 专属端点、身份验证、预签名上传流程和工作流阶段。
2. shared/skills/chatgpt-image-ad/prompting/guide.md — 模型专属提示词指南（gpt-image-2 擅长和不擅长什么，以及何时切换到 nano-banana）。
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. 模型必须是 gpt-image-2。 脚本会拒绝任何其他值。如果用户要求 nano-banana，请引导他们使用 nano-banana-image-ad。
2. 输出中不得包含平台或截图界面元素。 NO_CHROME_SUFFIX 始终启用（仅当广告概念确实需要界面元素时，才使用 --allow-chrome 覆盖——这种情况很少见）。
3. 始终启用边缘安全和字形安全后缀，除非明确指定 --no-safe-zone。这些设置能解决实际问题；不要默默移除。
4. 最多 5 张参考图片。 这是 Arcads 对 gpt-image-2 的硬性限制（观察到的错误为 400 Max 5 reference image(s) allowed）。脚本会强制执行此限制。
5. 此技能不会上传到 Meta。 仅生成图片。用户的工具栈中另有独立的广告制作技能——通过文件系统路径交接。
6. 生成前务必提供积分费用估算（参见 Arcads arcads-external-api 技能约定）。每次 gpt-image-2 调用生成一张图片；费用按 --n 变体数计算。

前提条件

• .env 文件中包含 ARCADS_BASIC_AUTH（首选，已编码）或 ARCADS_API_KEY
• 可选：在 .env 中设置 PRODUCT_ID、PROJECT_ID，使生成的素材存入正确的 Arcads 仪表板文件夹（会话文件夹模式请参阅 arcads-external-api 的 SKILL.md）
• 本地磁盘上的参考图片（PNG/JPG/JPEG/WEBP/GIF）。脚本会在内部处理 Arcads 预签名上传流程——你只需传入本地路径。

配置

• 基础 URL： https://external-api.arcads.ai（或 ARCADS_BASE_URL）。
• 身份验证： HTTP Basic。脚本优先使用预编码的 ARCADS_BASIC_AUTH 环境变量（例如 Basic ZXhhbXBsZTo=）；若不存在，则使用空密码对 ARCADS_API_KEY 进行编码。
• 端点： POST /v2/images/generate（请求）；GET /v1/assets/{id}（轮询，直到 status: generated）；状态变更后获取图片 URL。
• 参考图片上传： POST /v1/file-upload/get-presigned-url 返回 {presignedUrl, filePath}；将字节数据 PUT 到 presignedUrl；在 referenceImages 中传入 filePath 字符串。每个 filePath 只能使用一次——脚本会针对每个变体重新上传，以避免并行运行时发生冲突。

生成模式

模式	使用场景	必填项	可选项
image（默认）	生成全新的广告图片。	--prompt、--aspect-ratio	--image-ref（最多 5 张）
image_edit	修改现有图片（替换颜色、更改背景、添加元素）。	--prompt、--source	--image-ref（最多 5 张）

支持的宽高比

1:1、16:9、9:16。Arcads 的 /v2/images/generate 端点仅接受这三种比例（已通过实时请求确认：aspectRatio must be one of the following values: 1:1, 16:9, 9:16）。共享模板库中使用 2:3、3:2、4:5 等比例的模板，无法在此后端按原生比例渲染——请改用 1:1 并裁剪，或使用 KIE chatgpt-image-ad 同类技能；该技能通过专用的 /gpt4o-image/generate 端点原生支持 2:3 和 3:2。

用户必须提供的输入

输入	说明
种子提示词	用用户自己的话描述创意方向。你会重写它（见阶段 3）。
宽高比	上述 5 种之一。其他比例一律拒绝。
参考图片	可选，但如果广告中有特定产品，强烈建议提供。最多 5 张。
变体数量 N	默认为 1。上限为 5。
模式	image（默认）或 image_edit。
源图片	仅 image_edit 模式必需。

工作流

阶段 1：预检

1. .env 中存在 ARCADS_BASIC_AUTH 或 ARCADS_API_KEY。
2. （可选）arcads-external-api 会话文件夹已设置（见该 skill 的“会话设置”部分）。如果未设置 PRODUCT_ID / PROJECT_ID，生成的素材会存放在默认项目中——之后可以通过 POST /v1/assets/add-to-project 修正。
3. 健康检查：curl -sf -H "$AUTH" "$BASE_URL/v1/products" 返回 200。

阶段 2：收集输入

收集：种子提示词、模式、源图片（如为编辑模式）、参考图片路径、变体数量、宽高比。

阶段 3：重写提示词

阅读 shared/skills/image-ad-prompting/prompting/prompt-library.md。如果用户的需求符合某个模板，请检查 Model notes 区块——只有在 gpt-image-2 标记为 clean 或 preferred 时才继续。如果推荐使用 nano-banana，请建议先切换 skill 再生成。

填写 {placeholders} 并向用户展示重写后的提示词。询问：“使用此版本、进行编辑，还是重新开始？”重复此过程，直到用户批准。

对于新提示词（不匹配任何模板），请遵循 shared/skills/chatgpt-image-ad/prompting/guide.md § Phase 3b 中的结构。

阶段 4：确认积分费用（必须）

遵循 arcads-external-api 约定：提供预估积分费用（从 logs/arcads-api.jsonl 中匹配的过往调用记录读取，或查看 MASTER_CONTEXT.md 费率表）。必须等待用户明确确认后才能执行调用。

阶段 5：生成

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

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

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

按照 arcads-external-api skill 的约定，将每次调用记录到 logs/arcads-api.jsonl，包含 model=gpt-image-2、变体数量、referenceImages 数量以及返回的 asset_id。

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

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

• 小字是否乱码（这是 gpt-image-2 在正文密集时最常见的故障）
• 字标是否偏移（如果没有通过 --image-ref 传入品牌字标）
• 文本数量是否错误（例如出现 4 条 Slack 消息，而不是 3 条）
• iOS 对话框 / UI 的比例是否偏移

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

阶段 7：确认并交接

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

选中的变体现已可供 Meta-ad-builder skill 使用（用于处理克隆、文案和上传的独立 skill）。打印路径，以便用户通过管道传递。

也可以将选中的路径写入 ./generated/run-<ts>.jsonl（每行一个路径，并以 JSON 格式封装），供下游使用。

不在范围内——明确拒绝

• Meta 上传——由工具栈中的其他 skill 负责。
• Nano Banana / Gemini 图像生成——使用 nano-banana-image-ad。
• 视频、轮播、DCO 广告——仅支持图像。
• 广告文案撰写——由其他 skill 负责。
• 编辑共享提示词库——使用 image-ad-clone（在阶段 1 询问使用哪个后端）。

常见错误

• 401/403 → 按照 arcads-external-api 设置流程修正 .env。
• 400 Max 5 reference image(s) allowed → 将 --image-ref 数量减少到 ≤5。
• 422 validation/moderation → 收紧提示词；检查 aspectRatio 是否属于受支持的选项。
• 500 UNKNOWN_ERROR → 通常是重复使用了过期的预签名 filePath。脚本会为每个变体重新上传；如果仍然遇到此错误，请提交 issue，并附上响应中的 asset_id。

此技能管理的文件

• ~/.claude/skills/chatgpt-image-ad/SKILL.md — 此文件
• ~/.claude/skills/chatgpt-image-ad/scripts/generate_image.py — Arcads gpt-image-2 调用程序（预签名上传 + 生成 + 轮询 + 下载）

另请参阅

• shared/skills/chatgpt-image-ad/prompting/guide.md — 模型专属提示词指南（gpt-image-2 的优势/限制，以及何时切换到 nano-banana）
• shared/skills/image-ad-prompting/prompting/prompt-library.md — 共享模板库（30 多个条目，附有各模型的说明）
• shared/skills/image-ad-prompting/prompting/template-format.md — 新模板的条目框架
• shared/skills/image-ad-prompting/prompting/safety-suffixes.md — 3 个始终启用的防护措施
• image-ad-clone skill — 与后端无关的单一技能，可将现有广告逆向工程为可复用的库条目
• arcads-external-api skill — Arcads 底层约定（会话文件夹、额度成本、QA 流程、日志）
• nano-banana-image-ad skill — 同系列技能，适用于照片级真实感、生活方式及多参考图模板