# BrandCaster.studio

> AI-powered brand architect. Turns any website URL into a full brand identity, on-platform social posts, carousels, branded images and video. Two ways to use it: a credit-based human dashboard, and a pay-per-call HTTP API for AI agents.

## For AI Agents — Pay-Per-Call API

BrandCaster.studio exposes its core capabilities as a paid HTTP API designed for autonomous agents. No account, no API key, no signup — payment is settled per call in BSV using x402 micropayments.

- **Base URL (quick mode):** `https://brandcaster.studio/api/x402`
- **Base URL (BRC-121 mode):** `https://brandcaster.studio/api/x402/brc121` — currently returns `503 ERR_BRC121_NOT_CONFIGURED`; see "Payment modes" below.
- **Live machine-readable manifest:** `GET https://brandcaster.studio/.well-known/bsv-micropay-info` — returns JSON listing every endpoint, both payment modes (`modes.quick`, `modes.brc121`), current USD price, satoshi+BSV price, input schema, response shape, the receiving wallet address, and the full error code registry. Always read the manifest first; it is the source of truth. Legacy aliases: `/.well-known/x402-info` and `/api/x402/info`.
- **Human-readable docs:** `https://brandcaster.studio/developers`
- **Payment protocol:** [`bsv-micropay`](https://bsv-micropay-middleware.replit.app) — Express middleware + client SDK for pay-per-call BSV. Two modes supported by the protocol:
  - **Quick mode (enabled here):** address-based 402 with a hash-then-reveal HMAC challenge. Works with any BSV wallet (HandCash, Yours, Metanet, BRC-100). Flow: (1) call the endpoint without headers → receive `HTTP 402` with `challengeId` (secret, TLS only), `commitment` (HMAC hash), `challengeExpiresAt`, plus price and `payTo` address; (2) broadcast a BSV mainnet tx paying the amount to `payTo` AND embedding the `commitment` (the hash, NOT the secret) in an `OP_RETURN` output; (3) resend with headers `X-BSV-TxId`, `X-BSV-Challenge` (the secret), and `X-BSV-Challenge-Expiry`. The server verifies on WhatsOnChain, re-derives the commitment from the secret, and runs the handler. Each txId and challenge is single-use globally. Optional client SDK: `@ruthheasman/bsv-micropay-client`.
  - **BRC-121 mode (registered, not yet enabled here):** standards-compliant headers + BEEF transport per [BRC-121](https://brc.dev/121). Routes exist at `/api/x402/brc121/*` and currently return `503 ERR_BRC121_NOT_CONFIGURED`. Use quick mode for now. Client SDK when enabled: `@ruthheasman/bsv-micropay-client/brc121`.

### Endpoints (USD prices, all `POST application/json`)

- `POST /api/x402/analyze` — $0.06 — URL → brand identity (colors, typography, tone, audience, mission). Response includes `sourceImages[]` harvested from the page; reuse those on subsequent calls instead of generic stock photos.
- `POST /api/x402/post-pack` — $0.10 — One platform-tailored social post (X / Instagram / LinkedIn / TikTok / Threads / Facebook). Returns native-format caption, hashtags, headline, rendered image at the platform's native aspect ratio, alt text, and platform-specific extras (X thread, TikTok video script, Threads replies).
- `POST /api/x402/posts` — $0.06 — 4 platform-agnostic post plans (text only, no images).
- `POST /api/x402/image` — $0.10 — Render a single branded social image (Nano Banana Pro, 2K).
- `POST /api/x402/carousel` — $0.40 — 4-slide Instagram carousel: copy plan + 4 rendered 1:1 images.
- `POST /api/x402/video/grok` — $0.25 — 6s Grok Imagine 720p video from an image URL.
- `POST /api/x402/video/grok/extended` — $0.45 — ~12s Grok video (two clips concatenated).
- `POST /api/x402/video/veo` — $0.85 — Single Veo 3.1 Fast video from an image URL.
- `POST /api/x402/video/veo/extended` — $1.20 — ~12s Veo video (two clips concatenated).
- `POST /api/x402/video/extend/grok` — $0.25 — Append a Grok continuation clip to an existing video.
- `POST /api/x402/video/extend/veo` — $0.85 — Append a Veo continuation clip to an existing video.

### Image input rules (important)

For any endpoint that accepts a `screenshots[]` array of reference image URLs:
- Use only on-brand assets — typically `brand.sourceImages` returned from `/x402/analyze`, the brand's logo, or product shots from their own site.
- If you only have 1–2 on-brand images, pass just those — the renderer reuses them.
- Generic stock-photo and design-gallery URLs (Unsplash, Pexels, Pixabay, Shutterstock, Getty, Adobe Stock, Freepik, Behance, Dribbble, Flickr, etc.) are **rejected at the edge**. Don't try to pad the array with them.
- Pass the brand's URL via the `url` parameter wherever it's accepted — the server fetches the live page and grounds copy in real content. If the URL can't be fetched, supply `pageText` (1–3 paragraphs of landing-page text) as a fallback.

## For Humans — Credit-Based Dashboard

The web app at `https://brandcaster.studio/app` is a credit-funded creator dashboard. New users get free credits on signup; top up via HandCash. Same underlying capabilities as the agent API, packaged with a UI for screenshots upload, brand-run history, ZIP export, etc.

## Privacy

We store the brand assets you create. Nothing else. No analytics, no tracking pixels, no advertising, no data sharing. Auth is for security only. Full policy: `https://brandcaster.studio/privacy`.

## Technology

- Frontend: React + Vite + Tailwind
- Backend: Express on Node
- AI: Google Gemini (text + image), Kie.ai (Veo 3.1, Grok Imagine, Nano Banana Pro)
- Payments: HandCash Connect (BSV) for humans, x402 micropayments (BSV) for agents
- Auth: Replit Auth (OpenID Connect)
- Storage: PostgreSQL + object storage