{"openapi":"3.1.0","info":{"title":"overlayr — caption UGC clips (x402)","version":"3.0.0","description":"Burn TikTok-style captions onto UGC clips. Built for AI agents. 1,017 ready-made clips are built in (browse GET /clips for a clip_id), or bring your own footage with video_url. POST /overlay costs $0.10 USDC per render on Base via the x402 protocol."},"servers":[{"url":"https://overlayr.hatchagent.workers.dev"}],"paths":{"/overlay":{"post":{"summary":"Render styled captions onto a built-in clip or your own footage (x402 paid)","description":"Exactly one footage source: clip_id (1,017 built-in clips, the default) or video_url (bring-your-own-footage, public http(s) only). `text` is the canonical caption and renders at `position`; it takes precedence over legacy top_text/bottom_text (which still render at top/bottom).","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":128},"description":"Optional. A replayed key returns the original job instead of charging again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"oneOf":[{"required":["clip_id"]},{"required":["video_url"]}],"properties":{"clip_id":{"type":"string","maxLength":64,"description":"A clip id from GET /clips (1,017 ready-made UGC clips). Default footage source."},"video_url":{"type":"string","format":"uri","description":"Bring-your-own-footage: a public http(s) URL to your own video. SSRF-guarded; 50 MB and 60s caps apply at render time."},"text":{"type":"string","maxLength":140,"description":"Canonical caption. Takes precedence over top_text/bottom_text; renders at `position`."},"top_text":{"type":"string","maxLength":140,"description":"Legacy caption, renders at the top."},"bottom_text":{"type":"string","maxLength":140,"description":"Legacy caption, renders at the bottom."},"position":{"type":"string","enum":["top","middle","bottom"],"default":"top","description":"Vertical placement of `text`."},"stroke":{"type":"boolean","default":true,"description":"Text outline (stroke) on/off."},"color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$","default":"#FFFFFF","description":"Caption text color as #RRGGBB."},"font_size":{"type":"integer","minimum":24,"maximum":200,"default":72,"description":"Caption size in px. Clamped to 24-200."}}}}}},"responses":{"200":{"description":"Job queued."},"400":{"description":"Invalid request body: bad footage source, unknown clip_id shape, invalid styling field, or video_url pointing at a private/internal host."},"402":{"description":"Payment required — see PAYMENT-REQUIRED header."},"404":{"description":"clip_id is not in the catalog."},"429":{"description":"Rate limited or queue full — see Retry-After."},"502":{"description":"Facilitator or settlement failure; not charged."}}}},"/clips":{"get":{"summary":"Browse the clip catalog (free)","parameters":[{"name":"tag","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated tags; a clip must have all of them."},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Case-insensitive substring search over descriptions and tags."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1,"minimum":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"minimum":1,"maximum":100}}],"responses":{"200":{"description":"Paginated catalog of clips."}}}},"/overlay/result/{job_id}":{"get":{"summary":"Check render job status","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Job status; video_url when done."}}}}},"components":{"x-x402-accepts":{"scheme":"exact","network":"eip155:8453","amount":"100000","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0x9fb19734470aEF8b31fFdA83a8546B0213303581","maxTimeoutSeconds":300,"extra":{"name":"USD Coin","version":"2"}}}}