# surfugc

> The AI ad studio for e-commerce. AI ad studio for e-commerce: product photos, UGC-style video ads, a timeline editor, ad analysis and a variant matrix – with the price shown before every paid call.

## API
- Authentication: Create an API key in Settings → Developers and send it as `Authorization: Bearer atl_…`. Keys are scoped to your workspace, rate-limited to 120 requests per minute and can be revoked at any time.
- Spend gate: Every paid tool first answers with a cost preview (REST: HTTP 402 `confirmation_required` with `cost_credits`; MCP: `requires_confirmation: true`). Repeat the call with `max_credits` ≥ the cost to spend. Failed jobs are refunded automatically.
- MCP server: Streamable HTTP endpoint `POST /api/mcp` (JSON responses, protocol 2025-06-18): `initialize`, `tools/list`, `tools/call`, `ping`. Add it to Claude Desktop, Claude Code or any MCP client with your API key as a bearer header.
- REST: `GET /api/v1/tools` lists the tools with JSON Schemas; `POST /api/v1/tools/<name>` runs one with a JSON body; `GET /api/v1/me` returns your credit balance.
- Webhooks: Register HTTPS endpoints for `generation.succeeded`, `generation.failed`, `export.succeeded`, `export.failed`. Each POST carries `X-Surfugc-Signature: t=<unix>,v1=<hex>` – HMAC-SHA256 of `<t>.<raw body>` with the endpoint secret. Up to 3 attempts with backoff.

## Tools (REST and MCP)
- list_models (free): Image/video models with credit prices
- generate_image (paid): Product photos and ad stills
- generate_video (paid): Text or start-frame to video
- get_generation (free): Status and output URLs
- script_runner (free): Pasted script → ad with scenes and a timeline
- analyze_ad (paid): A–F breakdown + remake script
- get_timeline (free): The edited cut as tracks (ms timings)
- regenerate_scene (paid): Re-render one scene (still or clip)
- render_variant_matrix (free): Hook variants × formats to MP4
- export_ad (free): Render the edit to MP4 (C2PA by default)
- get_exports (free): Export status and download URLs
- list_ads (free): Your recent ads

## Endpoints
- MCP: https://surfugc.com/api/mcp
- REST: https://surfugc.com/api/v1/tools
- Docs: https://surfugc.com/developers
- Pricing: https://surfugc.com/pricing