Developers

Your ad studio, from any agent

One MCP server and REST API for the whole pipeline – generate, script, analyze, edit the timeline, export. Every paid call shows its price first and only spends after confirmation.

Create an API key llms.txt

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

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

Quick start

curl -X POST https://surfugc.com/api/v1/tools/generate_image \
  -H "Authorization: Bearer $SURFUGC_KEY" -H "Content-Type: application/json" \
  -d '{"prompt":"Amber serum bottle on travertine, soft window light","aspect_ratio":"4:5"}'
# → 402 {"code":"confirmation_required","cost_credits":9}
# repeat with "max_credits": 9 to spend

MCP client config

{
  "mcpServers": {
    "surfugc": {
      "type": "http",
      "url": "https://surfugc.com/api/mcp",
      "headers": {
        "Authorization": "Bearer atl_…"
      }
    }
  }
}