README.md

metadata

title: Hawbeez Ad Creative Studio
emoji: ✨
colorFrom: green
colorTo: blue
sdk: docker
app_port: 7860

Hawbeez Ad Creative Studio

Full-stack app: paste a Hawbeez product page URL → scrape product data → run a deep marketing analysis (OpenAI) → generate 20 ad creative packages (product-focused + no-product) for Meta (Facebook/Instagram). Built for Hawbeez eco-friendly wooden and Montessori toys.

What it does

1. Scrape – Fetches the Hawbeez product page and extracts name, description, price, images, brand, category (JSON-LD, meta tags, Shopify product JSON).
2. Analyze – GPT-based analysis: positioning, taglines, ideal customer (parents/kids), emotional triggers, price framing, ad angles, USPs, copy direction.
3. Creatives – Generates 20 ad concepts (17 product-focused, 3 no-product) with headlines, body copy, image prompts, and layout notes tailored for toys and parent audiences.
4. Generate ad images – Select any of the 20 creatives, pick a Replicate image model, and generate actual ad images from the prompts (via Replicate).

Setup

Backend (Python)

cd backend
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt

Create a .env file (copy from .env.example if present, or add):

OPENAI_API_KEY=sk-your-key-here
REPLICATE_API_TOKEN=r8_your-replicate-token   # optional; for generating ad images

Get a Replicate token at https://replicate.com/account/api-tokens (needed only for the "Generate ads" feature).

Optional – save generated creatives to Cloudflare R2:
Set R2_ENDPOINT, R2_BUCKET_NAME, R2_ACCESS_KEY, and R2_SECRET_KEY in .env. When set, each generated ad image is uploaded to R2 and the API returns the R2 presigned URL (7-day expiry) instead of the temporary Replicate URL.

Run the API:

uvicorn app.main:app --reload --host 0.0.0.0 --port 8005

API docs: http://127.0.0.1:8005/docs

Frontend (React + Vite)

cd frontend
npm install
npm run dev

App: http://localhost:5173

The frontend is configured to proxy /api to http://127.0.0.1:8005, so run the backend first.

Creating a user (script only)

The app requires login. Create users with the script (no signup UI). Use the backend venv so dependencies are available:

# From repo root (use backend venv)
backend/.venv/bin/python backend/scripts/create_user.py --username admin --password yourpassword

Or from the backend directory (after activating the venv):

cd backend
source .venv/bin/activate   # Windows: .venv\Scripts\activate
python scripts/create_user.py -u admin -p yourpassword

Users are stored in backend/data/users.json. For production, set JWT_SECRET in .env to a long random string.

Usage

1. Open http://localhost:5173 and sign in with a user created via the script above.
2. Paste a Hawbeez product URL (e.g. https://hawbeez.com/products/wooden-three-letter-words-toy)
3. Click Generate
4. Wait for scrape → analysis → creatives (about 1–2 minutes)
5. Browse Product card, Marketing Analysis, and Ad Creatives (click a creative to expand copy + image prompt).
6. Generate ad images: tick the checkboxes for the creatives you want, choose an image model (e.g. nano-banana, flux-2-max), click Generate ads. Generated images appear in a grid below (Replicate URLs may expire after a while).

API

• POST /api/run – Body: { "url": "https://hawbeez.com/products/..." }
  Returns: { product_data, analysis, ad_creatives }
• POST /api/run/stream – Same as run, streamed via SSE (step updates).
• POST /api/scrape – Body: { "url": "..." }
  Returns: product data only
• GET /api/image-models – Returns list of Replicate image models for ad generation
• POST /api/generate-ads – Body: { "creatives": [ ... ], "model_key": "nano-banana" }
  Returns: { "results": [{ "creative_id", "image_url", "error" }] }
• GET /api/gallery/creatives – Paginated gallery (presigned URLs when R2 is used).
• GET /api/logo – Hawbeez logo for Replicate reference image.

Project layout

Hawbeez_Creative_Studio/
├── backend/
│   ├── app/
│   │   ├── main.py         # FastAPI app, /api/run, /api/scrape, /api/generate-ads
│   │   ├── scraper.py      # Hawbeez product page scraper (Shopify)
│   │   ├── llm.py          # OpenAI client
│   │   ├── analysis.py     # Deep product analysis (toys/parents)
│   │   ├── creatives.py    # Ad creative generation (toys/parents)
│   │   └── replicate_image.py
│   ├── requirements.txt
│   └── data/               # users.json, gallery/
├── frontend/
│   ├── src/
│   │   ├── App.jsx
│   │   ├── Gallery.jsx
│   │   └── index.css
│   ├── index.html
│   ├── package.json
│   └── vite.config.js
├── Dockerfile
└── README.md

Deploy on Hugging Face

1. Create a new Space at huggingface.co/new-space. Choose Docker as the SDK.
2. Push this repo into the Space.
3. Secrets: In the Space → Settings → Repository secrets, add:
   • OPENAI_API_KEY – required for analysis and creatives
   • REPLICATE_API_TOKEN – required for "Generate ads"
   • JWT_SECRET – optional; set a long random string for production
   • R2 (optional): R2_ACCESS_KEY, R2_SECRET_KEY, R2_BUCKET_NAME, R2_ENDPOINT
4. DATA_DIR: On Hugging Face, only /tmp is writable. The Dockerfile sets DATA_DIR=/tmp/hawbeez-data. Reference uploads and gallery index use this path.

Reference image URLs must be reachable by Replicate. Use the app URL (e.g. https://your-username-hawbeez-creative-studio.hf.space) or set secret BASE_URL.

Notes

• OPENAI_API_KEY is required for analysis and creatives; scraping works without it.
• REPLICATE_API_TOKEN is required only for "Generate ads".
• The backend uses gpt-4o-mini by default. Analysis and creatives are tuned for Hawbeez (wooden toys, Montessori, parents, gifting).