Skip to content

Hainrixz/claude-ads / ads

Free-first paid advertising audit and optimization skill, focused on the 3 platforms where 95% of advertiser spend lives: Meta, Google, TikTok. Guided onboarding (/ads start) saves context once and step-by-step OAuth walkthroughs; continuous coach (/ads next) ranks Quick Wins after each audit. ~158 weighted checks with scoring, parallel agents, industry templates, and AI creative generation.

FileKindSize
SKILL.mdskill md18.6 KB
references/additional-platforms.mdmarkdown3.6 KB
references/audit-history-schema.jsonconfig2.5 KB
references/audit-methodology.mdmarkdown4.3 KB
references/audit-output-schema.jsonconfig4.9 KB
references/benchmarks-cross.mdmarkdown1003 B
references/benchmarks-google.mdmarkdown1.6 KB
references/benchmarks-social.mdmarkdown2.6 KB
references/benchmarks.mdmarkdown929 B
references/bidding-google.mdmarkdown5.2 KB
references/bidding-meta.mdmarkdown1.8 KB
references/bidding-strategies.mdmarkdown989 B
references/bidding-tiktok.mdmarkdown2.0 KB
references/brand-dna-template.mdmarkdown6.9 KB
references/budget-allocation.mdmarkdown5.8 KB
references/compliance-changes-2025-2026.mdmarkdown2.5 KB
references/compliance-platforms.mdmarkdown3.6 KB
references/compliance-privacy.mdmarkdown3.1 KB
references/compliance.mdmarkdown1.6 KB
references/conciencia-schema.jsonconfig5.3 KB
references/conciencia.mdmarkdown5.2 KB
references/conversion-tracking.mdmarkdown1.2 KB
references/copy-frameworks.mdmarkdown8.9 KB
references/gaql-notes.mdmarkdown2.8 KB
references/google-audit-notes.mdmarkdown3.9 KB
references/google-audit.mdmarkdown12.5 KB
references/google-changelog-30d.mdmarkdown3.6 KB
references/google-creative-specs.mdmarkdown3.7 KB
references/image-providers.mdmarkdown4.9 KB
references/mcp-integration.mdmarkdown5.7 KB
references/mcp-meta-integration.mdmarkdown5.8 KB
references/meta-audit.mdmarkdown12.4 KB
references/meta-changelog-30d.mdmarkdown4.0 KB
references/meta-creative-specs.mdmarkdown4.5 KB
references/platform-specs-cross.mdmarkdown1.3 KB
references/platform-specs.mdmarkdown799 B
references/profile-schema.jsonconfig4.5 KB
references/scoring-system.mdmarkdown6.1 KB
references/setup-google.mdmarkdown7.1 KB
references/setup-meta-developers.mdmarkdown4.7 KB
references/setup-meta.mdmarkdown7.0 KB
references/setup-tiktok.mdmarkdown5.2 KB
references/setup-zernio.mdmarkdown4.5 KB
references/tiktok-audit.mdmarkdown10.1 KB
references/tiktok-changelog-30d.mdmarkdown3.5 KB
references/tiktok-creative-specs.mdmarkdown4.8 KB
references/tracking-cross.mdmarkdown1.5 KB
references/tracking-google.mdmarkdown2.8 KB
references/tracking-meta.mdmarkdown2.4 KB
references/tracking-tiktok.mdmarkdown1.5 KB
references/update-cost-warning.mdmarkdown2.0 KB
references/voice-to-style.mdmarkdown3.9 KB
research-sources/README.mdmarkdown883 B
research-sources/claude-research.mdmarkdown3.9 KB
research-sources/gemini-research.mdmarkdown10.2 KB
research-sources/google-audit-checklists.mdmarkdown25.9 KB
research-sources/google-optimization-logic.mdmarkdown11.9 KB
research-sources/google-platform-specs.mdmarkdown16.6 KB

references/image-providers.md

View on GitHub
# Image Generation Providers

<!-- Updated: 2026-04-01 -->
<!-- Used by: ads-generate, ads-photoshoot, visual-designer agent -->

## Default Provider: banana-claude

banana-claude (v1.4.1) is the default image generation provider. It acts as a Creative Director
layer on top of Google Gemini, providing 5-component prompt engineering, 9 domain modes,
brand presets, cost tracking, and post-processing.

### Prerequisites
- banana-claude installed (`/banana setup` to verify)
- nanobanana-mcp configured with GOOGLE_AI_API_KEY
- No additional pip packages needed (banana uses stdlib only)

### MCP Tools (Primary Method)

| Tool | Purpose | Key Parameters |
|------|---------|----------------|
| `set_aspect_ratio` | Configure ratio for next generation | ratio: "16:9", "1:1", "9:16", etc. |
| `set_model` | Switch Gemini model | model: "gemini-3.1-flash-image-preview" (default) |
| `gemini_generate_image` | Text-to-image generation | prompt: (string) |
| `gemini_edit_image` | Modify existing image | imagePath, prompt |
| `get_image_history` | Review session generations | (none) |

### Domain Modes for Ad Creative

| Mode | Use For | Ad Type |
|------|---------|---------|
| Product | E-commerce packshots, product ads | Shopping, PMax, Meta catalog |
| Editorial | Brand awareness, lifestyle campaigns | Meta Feed, YouTube, LinkedIn |
| Cinema | Dramatic storytelling, video thumbnails | YouTube, TikTok, Demand Gen |
| Portrait | People-centric ads, testimonials | Meta, LinkedIn, Google Display |
| UI/Web | App install ads, SaaS screenshots | Google UAC, Meta app install |
| Logo | Brand identity, favicon generation | All platforms (identity assets) |
| Landscape | Environment, travel, real estate | Google Display, YouTube |
| Infographic | Data-driven ads, comparison charts | LinkedIn, Google Display |
| Abstract | Background textures, patterns | All (supporting assets) |

### 5-Component Prompt Formula

Banana constructs optimized prompts using:
1. [SUBJECT]: Physical details, appearance, material
2. [ACTION]: What it's doing, pose, state
3. [LOCATION/CONTEXT]: Where, when, atmosphere
4. [COMPOSITION]: Camera angle, framing, perspective
5. [STYLE]: Camera/lens specs, lighting, brand voice mapped attributes

Visual-designer agent builds these components from campaign brief + brand profile.

### Pricing (Gemini via banana)

| Resolution | Cost/Image | Use Case |
|------------|-----------|----------|
| 512px | $0.020 | Quick drafts, concepts |
| 1K | $0.039 | Standard web assets |
| 2K (recommended) | $0.078 | Quality ad creatives |
| 4K | $0.156 | Print, hero images |
| Batch API | 50% off | Bulk campaign generation |

### Aspect Ratios (14 supported)

| Ratio | Dimensions | Platform Use |
|-------|-----------|-------------|
| 1:1 | 1080x1080 | Meta Feed, LinkedIn, Carousel |
| 4:5 | 1080x1350 | Meta Feed (preferred), Instagram |
| 9:16 | 1080x1920 | TikTok, Reels, Shorts, Stories |
| 16:9 | 1920x1080 | YouTube, Google Display, LinkedIn |
| 3:2 | 1200x800 | DSLR standard, photo prints |
| 2:3 | 800x1200 | Pinterest, posters |
| 21:9 | Cinematic | Ultra-wide banners |
| 4:1 | 1200x300 | Website banners |
| 1:4 | Vertical banner | Mobile banners |

Note: Gemini does not natively support 1.91:1. Use 16:9 and crop to 1200x628 for Google PMax/LinkedIn.

### Brand Presets

banana supports brand presets stored at `~/.banana/presets/NAME.json`.
The ads-generate skill auto-creates a preset from brand-profile.json before generation.

Preset schema:
- colors: array of hex values from brand DNA
- style: visual style description from brand aesthetic
- mood: mood keywords from brand voice
- default_ratio: "16:9" (or platform-specific)
- default_resolution: "2K"

### Cost Tracking

banana logs all generations to `~/.banana/costs.json`.
ads-generate reads this after generation and includes cost summary in generation-manifest.json.

---

## Fallback Providers

If banana is not installed, these providers can be used directly via generate_image.py (deprecated).

### OpenAI (gpt-image-1)
- Env: `OPENAI_API_KEY`
- Price: ~$0.040/image (1024x1024), ~$0.060 (1024x1536)
- Package: `openai>=1.75.0`

### Stability AI (stable-diffusion-3.5-large)
- Env: `STABILITY_API_KEY`
- Price: ~$0.065/image flat
- Package: `stability-sdk>=0.8.4`

### Replicate (FLUX.1 Pro)
- Env: `REPLICATE_API_TOKEN`
- Price: ~$0.055/image
- Package: `replicate>=1.0.4`

---

## Error Reference

| Error | Cause | Fix |
|-------|-------|-----|
| banana MCP not found | nanobanana-mcp not configured | Run `/banana setup` |
| IMAGE_SAFETY | Safety filter triggered | Rephrase; use abstraction or artistic framing |
| 429 Too Many Requests | Rate limit | banana auto-retries with exponential backoff |
| FAILED_PRECONDITION | Billing not enabled | Enable billing in Google AI Studio |

### Rate Limits (Gemini via banana)

| Tier | RPM | Daily Images |
|------|-----|-------------|
| Free | 5-15 | 20-500 |
| Tier 1 (<$250 spend) | 150 | 1,500 |
| Tier 2 (>$250 spend) | 1,000+ | Unlimited |
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall