{"openapi":"3.0.0","info":{"title":"Tarantillo Public API","version":"1.0.0","description":"API for programmatic video creation using AI."},"servers":[{"url":"/v1","description":"Public API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key authentication. Use: Bearer trk_xxx"}},"schemas":{},"parameters":{}},"paths":{"/videos":{"post":{"tags":["Videos"],"summary":"Create a new video","description":"Initiates AI-powered video creation from text content. Returns a job ID for polling.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Project name (used in filename when downloading)"},"content":{"type":"object","properties":{"text":{"type":"string","minLength":10,"maxLength":50000,"description":"Text content for the video (10-50000 chars)"},"urls":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":5,"description":"URLs to scrape for content (future feature)"}},"required":["text"]},"script":{"type":"object","properties":{"instructions":{"type":"string","maxLength":2000,"description":"Custom instructions for the AI script writer"},"maxSlides":{"type":"integer","minimum":1,"maximum":30,"default":5,"description":"Maximum number of slides (1-30)"},"language":{"type":"string","enum":["en-US","pt-BR","es-ES","fr-FR","de-DE","it-IT","ja-JP","ko-KR","zh-CN"],"default":"en-US","description":"Script language"},"includeIntro":{"type":"boolean","default":true,"description":"Include an intro slide"},"includeOutro":{"type":"boolean","default":true,"description":"Include an outro slide"}},"default":{}},"visuals":{"type":"object","properties":{"aspectRatios":{"type":"array","items":{"type":"string","enum":["16:9","9:16","1:1"]},"minItems":1,"maxItems":3,"default":["16:9"],"description":"Aspect ratios to render (1-3)"},"quality":{"type":"string","enum":["good","awesome"],"default":"good","description":"Image quality"},"stylePreset":{"type":"string","enum":["none","photorealistic","anime","digital_art","corporate_flat","comic_book","whiteboard","watercolor","tarot","cute_3d","stickman","isometric","paper_cutout","retro_pixel","neon_cyberpunk","claymation","vintage_poster"],"description":"Visual style preset (e.g., photorealistic, anime, watercolor, etc.)"}},"default":{}},"audio":{"type":"object","properties":{"voiceId":{"type":"string","description":"Voice ID for narration"},"quality":{"type":"string","enum":["good","awesome"],"default":"good","description":"Audio quality"}},"default":{}}},"required":["content"]}}}},"responses":{"202":{"description":"Video creation started","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Pipeline job ID for polling"},"projectId":{"type":"string","description":"Created project ID"},"status":{"type":"string","enum":["queued"]},"estimatedCredits":{"type":"number","description":"Estimated credits to be consumed"},"balance":{"type":"number","description":"Credit balance after this operation"},"breakdown":{"type":"object","properties":{"script":{"type":"number","description":"Credits for script generation"},"images":{"type":"number","description":"Credits for image generation"},"audio":{"type":"number","description":"Credits for audio generation"},"render":{"type":"number","description":"Credits for video rendering"}},"required":["script","images","audio","render"],"description":"Per-operation cost breakdown"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","projectId","status","estimatedCredits","balance","breakdown","createdAt"]}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["INSUFFICIENT_CREDITS"]},"message":{"type":"string"},"required":{"type":"number","description":"Credits required for this operation"},"available":{"type":"number","description":"Current credit balance"},"breakdown":{"type":"object","properties":{"script":{"type":"number","description":"Credits for script generation"},"images":{"type":"number","description":"Credits for image generation"},"audio":{"type":"number","description":"Credits for audio generation"},"render":{"type":"number","description":"Credits for video rendering"}},"required":["script","images","audio","render"],"description":"Per-operation cost breakdown"}},"required":["code","message","required","available"]}},"required":["error"]}}}}}},"get":{"tags":["Videos"],"summary":"List videos","description":"List all videos created by the authenticated API key.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Video list","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["queued","processing","completed","failed"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"}},"required":["id","status","createdAt"]}},"total":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["items","total","hasMore"]}}}}}}},"/videos/{id}":{"get":{"tags":["Videos"],"summary":"Get video status","description":"Poll for video creation status. Returns download URL when completed.","parameters":[{"schema":{"type":"string","description":"Pipeline job ID"},"required":true,"description":"Pipeline job ID","name":"id","in":"path"}],"responses":{"200":{"description":"Video status","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["queued","processing","completed","failed"]},"progress":{"type":"object","properties":{"stage":{"type":"string"},"percentage":{"type":"number"}},"required":["stage"]},"result":{"type":"object","properties":{"downloadUrl":{"type":"string","format":"uri","description":"Presigned download URL (1 hour TTL)"},"duration":{"type":"number","description":"Video duration in seconds"},"aspectRatio":{"type":"string"},"slideCount":{"type":"number"}},"required":["downloadUrl","duration","aspectRatio","slideCount"]},"videos":{"type":"array","items":{"type":"object","properties":{"aspectRatio":{"type":"string","description":"Aspect ratio (e.g., '16:9', '9:16', '1:1')"},"downloadUrl":{"type":"string","format":"uri","description":"Presigned download URL (1 hour TTL)"},"duration":{"type":"number","description":"Video duration in seconds"}},"required":["aspectRatio","downloadUrl","duration"]},"description":"All rendered videos (one per aspect ratio)"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"creditsUsed":{"type":"number"},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"}},"required":["id","status","creditsUsed","createdAt"]}}}}}}}}}