{"type":"service","name":"ViralClaw API","description":"Video captioning API for AI agents. Transform videos into viral shorts with styled captions.","base_url":"https://api.viral-claw.com/api/v1","auth":{"type":"api_key","header":"X-API-Key"},"pricing":{"free_credits":3,"credit_pack":{"price_usd":29,"credits":200,"expiration":"never"},"credit_unit":"1 credit = 1 minute of video"}}
{"type":"endpoint","method":"GET","path":"/api/v1/credits","description":"Check credit balance, plan, and rate limit","auth":true,"response":{"credits":487,"plan":"free","rate_limit_per_minute":30}}
{"type":"endpoint","method":"GET","path":"/api/v1/me","description":"Full account info with API key details and today's usage","auth":true,"response":{"api_key":{"id":1,"name":"default","key_hint":"...abc12345","credits":487,"rate_limit_per_minute":30,"is_active":true},"plan":"free","usage_today":{"jobs_created":3,"credits_used":5}}}
{"type":"endpoint","method":"GET","path":"/api/v1/styles","description":"List available caption styles","auth":true,"response":{"styles":[{"id":"hormozi","name":"Hormozi","description":"Bold, impactful captions"},{"id":"mrbeast","name":"MrBeast","description":"High energy, colorful"},{"id":"tiktok","name":"TikTok","description":"Glowing neon, trendy"},{"id":"minimal","name":"Minimal","description":"Clean, simple"},{"id":"karaoke","name":"Karaoke","description":"Word-by-word highlight"}]}}
{"type":"endpoint","method":"GET","path":"/api/v1/usage","description":"Usage history with daily breakdown","auth":true,"params":{"days":{"type":"int","default":7,"min":1,"max":30}},"response":{"period":{"from":"2026-02-01","to":"2026-02-07"},"summary":{"total_jobs":12,"completed_jobs":10,"failed_jobs":2,"credits_used":45,"total_duration_seconds":2700.0},"daily":[{"date":"2026-02-07","jobs":3,"credits":15,"duration":900.0}]}}
{"type":"endpoint","method":"POST","path":"/api/v1/add-captions","description":"Add captions to a single video","auth":true,"content_type":"multipart/form-data","fields":{"video_url":{"type":"string","description":"URL of video to process (or upload via 'video' field)"},"video":{"type":"file","description":"Video file upload (alternative to video_url)"},"style":{"type":"string","default":"hormozi","enum":["hormozi","mrbeast","tiktok","minimal","karaoke"]},"language":{"type":"string","description":"Language code (e.g. en, pt, es)"},"webhook_url":{"type":"string","description":"URL to receive job completion callback"},"webhook_token":{"type":"string","description":"Token sent back in webhook header for verification"},"priority":{"type":"string","default":"normal","enum":["normal","high"]}},"response":{"job_id":42},"credits":"1 per minute of video (rounded up)"}
{"type":"endpoint","method":"POST","path":"/api/v1/generate-shorts","description":"Full pipeline: long video to multiple viral shorts","auth":true,"content_type":"multipart/form-data","fields":{"video_url":{"type":"string","description":"URL of long video"},"video":{"type":"file","description":"Video file upload"},"style":{"type":"string","default":"hormozi","enum":["hormozi","mrbeast","tiktok","minimal","karaoke"]},"language":{"type":"string","description":"Language code"},"count":{"type":"int","default":5,"min":1,"max":20,"description":"Number of shorts to generate"},"webhook_url":{"type":"string"},"priority":{"type":"string","default":"normal","enum":["normal","high"]}},"response":{"job_id":43}}
{"type":"endpoint","method":"GET","path":"/api/v1/jobs/{job_id}","description":"Poll job status and get results","auth":true,"response":{"job_id":42,"status":"done","created_at":"2026-02-08T09:00:00Z","completed_at":"2026-02-08T09:01:02Z","output_url":"https://pub-xxx.r2.dev/outputs/42/captioned.mp4","error":null,"result":{}}}
{"type":"endpoint","method":"GET","path":"/api/v1/shorts","description":"List your shorts (paginated)","auth":true,"params":{"page":{"type":"int","default":1},"per_page":{"type":"int","default":20},"status":{"type":"string","enum":["queued","processing","done","failed"]}},"response":{"shorts":[],"total":0,"page":1,"per_page":20,"pages":0}}
{"type":"endpoint","method":"GET","path":"/api/v1/shorts/{short_id}","description":"Get single short with signed download URL","auth":true,"response":{"short_id":1,"status":"done","output_url":"https://signed-url...","created_at":"2026-02-08T09:00:00Z"}}
{"type":"endpoint","method":"DELETE","path":"/api/v1/shorts/{short_id}","description":"Delete a short","auth":true,"response_status":204}
{"type":"endpoint","method":"GET","path":"/health","description":"API health check","auth":false,"response":{"status":"ok"}}
{"type":"errors","codes":{"400":"Bad request (invalid style, missing video, etc)","401":"Invalid or missing API key","402":"Insufficient credits","403":"Feature not available on your plan","404":"Job or short not found","429":"Rate limit exceeded","500":"Server error"},"format":{"detail":"Human-readable error message"}}
{"type":"rate_limits","free":{"requests_per_minute":10},"paid":{"requests_per_minute":30},"exceeded_response":{"status":429,"header":"Retry-After"}}
{"type":"webhooks","description":"POST callback when job completes","payload":"Full job object including output_url","verification":"webhook_token sent back in request header"}