chatgpt-image-ad (Arcads)
Generate one or more standalone Meta ad image creatives via Arcads' POST /v2/images/generate with model: "gpt-image-2". Hands the image paths off to your Meta-ad-builder skill — this skill does not upload to Meta itself.
Read order
- This file — Arcads-specific endpoint, auth, presigned upload flow, workflow phases.
- shared/skills/chatgpt-image-ad/prompting/guide.md — model-specific prompting (what gpt-image-2 is good/bad at, when to switch to nano-banana).
- shared/skills/image-ad-prompting/prompting/prompt-library.md — 30+ validated templates with per-model notes.
- shared/skills/image-ad-prompting/prompting/safety-suffixes.md — the 3 always-on guards.
- scripts/generate_image.py — the helper script (Python stdlib only).
Hard rules — never relax
- Model is
gpt-image-2. The script refuses any other value. If the user asks for nano-banana, point them at nano-banana-image-ad.
- No platform/screenshot chrome in output.
NO_CHROME_SUFFIX is always on (override with --allow-chrome only when the ad's concept requires chrome — rare).
- Edge-safe + glyph-safety suffixes always on unless
--no-safe-zone is explicit. They fix real failures; don't remove silently.
- Max 5 reference images. Hard Arcads cap for gpt-image-2 (observed
400 Max 5 reference image(s) allowed). The script enforces.
- No Meta upload from this skill. Image generation only. The user has a separate ad-builder skill in their stack — hand off via filesystem paths.
- Always present a credit-cost estimate before generating (see Arcads
arcads-external-api skill conventions). Each gpt-image-2 call is one image; multiply by --n variants.
Prerequisites
.env containing ARCADS_BASIC_AUTH (preferred, pre-encoded) OR ARCADS_API_KEY- Optional:
PRODUCT_ID, PROJECT_ID in .env so generated assets land in the right Arcads dashboard folder (see arcads-external-api SKILL.md for the session-folder pattern)
- Reference images on local disk (PNG/JPG/JPEG/WEBP/GIF). The script handles the Arcads presigned-upload flow internally — you pass local paths.
Configuration
- Base URL:
https://external-api.arcads.ai (or ARCADS_BASE_URL).
- Auth: HTTP Basic. The script prefers a pre-encoded
ARCADS_BASIC_AUTH env var (e.g. Basic ZXhhbXBsZTo=); falls back to encoding ARCADS_API_KEY with an empty password.
- Endpoint:
POST /v2/images/generate (request); GET /v1/assets/{id} (poll until status: generated); image URL fetched once status flips.
- Reference uploads:
POST /v1/file-upload/get-presigned-url returns {presignedUrl, filePath}; PUT the bytes to presignedUrl; pass the filePath string in referenceImages. Each filePath is single-use — the script re-uploads per variant so parallel runs don't collide.
Generation modes
| Mode | When to use | Required | Optional |
|---|
image (default) | Generate a brand-new ad image. | --prompt, --aspect-ratio | --image-ref (up to 5) |
image_edit | Modify an existing image (swap colors, change background, add element). | --prompt, --source | --image-ref (up to 5) |
Supported aspect ratios
1:1, 16:9, 9:16. Only these three are accepted by Arcads' /v2/images/generate endpoint (confirmed live: aspectRatio must be one of the following values: 1:1, 16:9, 9:16). Templates in the shared library that use 2:3, 3:2, 4:5, etc. won't render at their native ratio on this backend — fall back to 1:1 and crop, or use the KIE chatgpt-image-ad sibling which supports 2:3 and 3:2 natively via its dedicated /gpt4o-image/generate endpoint.
Inputs the user must provide
| Input | Notes |
|---|
| Seed prompt | The creative direction in their words. You will rewrite it (see Phase 3). |
| Aspect ratio | One of the 5 above. Reject anything else. |
| Reference image(s) | Optional but strongly recommended when the ad features a specific product. Up to 5. |
Variant count N | Default 1. Cap at 5. |
| Mode | image (default) or image_edit. |
| Source image | Required only for image_edit. |
Workflow
Phase 1: Preflight
.env exists with ARCADS_BASIC_AUTH or ARCADS_API_KEY.- (Optional)
arcads-external-api session folder is set up (see that skill's "Session setup" section). If PRODUCT_ID / PROJECT_ID aren't set, generated assets land in the default project — you can fix later via POST /v1/assets/add-to-project.
- Health-check:
curl -sf -H "$AUTH" "$BASE_URL/v1/products" returns 200.
Phase 2: Gather inputs
Collect: seed prompt, mode, source (if edit), reference paths, variant count, aspect ratio.
Phase 3: Prompt rewrite
Read shared/skills/image-ad-prompting/prompting/prompt-library.md. If the user's brief maps onto a template, check the Model notes block — only proceed if gpt-image-2 is marked clean or preferred. If nano-banana is preferred, suggest switching skills before generating.
Fill the {placeholders} and show the user the rewritten prompt. Ask "Use this, edit it, or start over?" Loop until approved.
For fresh prompts (no template match), follow the structure in shared/skills/chatgpt-image-ad/prompting/guide.md § Phase 3b.
Phase 4: Credit cost confirmation (MANDATORY)
Per arcads-external-api conventions: present an estimated credit cost (read from logs/arcads-api.jsonl for matching past calls, or MASTER_CONTEXT.md rate table). Wait for explicit confirmation before firing.
Phase 5: Generate
~/.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
Each line on stdout is one JSON variant (variant, path, asset_id, width, height, prompt, mode, aspect_ratio, model).
Log each call to logs/arcads-api.jsonl with model=gpt-image-2, the variant count, referenceImages count, and the returned asset_ids, per arcads-external-api skill conventions.
Phase 6: Visual QA (MANDATORY)
For each completed variant, read the image and inspect for:
- Garbled small text (most common gpt-image-2 failure on dense body text)
- Wordmark drift (if a brand wordmark wasn't passed as
--image-ref)
- Wrong text count (e.g. 4 Slack messages instead of 3)
- iOS dialog / UI proportion drift
If defects: regenerate with a revised prompt explicitly correcting the issue (see shared/skills/chatgpt-image-ad/prompting/guide.md § Retry mode). Cap at 2 retries per variant.
Phase 7: Confirm and hand off
Show all paths to the user. Ask "Use all / use these specific ones / regenerate / cancel."
Selected variants are now ready for your Meta-ad-builder skill (the separate skill that handles cloning, copy, and upload). Print the paths so the user can pipe them.
Optionally, write the selected paths to ./generated/run-<ts>.jsonl (one path per line, JSON-wrapped) for downstream consumption.
Out of scope — fail clearly
- Meta upload — different skill in your stack.
- Nano Banana / Gemini image generation — use
nano-banana-image-ad.
- Video, carousel, DCO ads — image only.
- Ad copy writing — different skill.
- Editing the shared prompt library — use
image-ad-clone (asks which backend at Phase 1).
Common errors
- 401/403 → fix
.env per arcads-external-api setup flow.
- 400 Max 5 reference image(s) allowed → reduce
--image-ref count to ≤5.
- 422 validation/moderation → tighten the prompt; check that
aspectRatio is in the supported set.
- 500 UNKNOWN_ERROR → usually a stale presigned filePath being reused. The script re-uploads per variant; if you still see this, file an issue with the
asset_id from the response.
Files this skill owns
~/.claude/skills/chatgpt-image-ad/SKILL.md — this file~/.claude/skills/chatgpt-image-ad/scripts/generate_image.py — Arcads gpt-image-2 caller (presigned upload + generate + poll + download)
See also