{"openapi":"3.1.0","info":{"title":"agent-media API","version":"1.0.0","description":"AI UGC video production API. Generate talking head videos, product reviews, and styled subtitles.","contact":{"url":"https://agent-media.ai"},"license":{"name":"Apache-2.0"},"termsOfService":"https://agent-media.ai/terms"},"servers":[{"url":"https://api-v2-production-2f24.up.railway.app","description":"Production API"}],"paths":{"/v1/generate/ugc_video":{"post":{"operationId":"ugc_video","summary":"Generate a UGC-style video from a script or prompt","tags":["generate"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"script":{"type":"string","minLength":50,"maxLength":3000},"prompt":{"type":"string","minLength":1,"maxLength":1000},"product_url":{"type":"string","format":"uri"},"actor_slug":{"type":"string","minLength":1,"maxLength":100},"persona_slug":{"type":"string","minLength":1,"maxLength":100},"face_photo_url":{"type":"string","format":"uri"},"voice":{"type":"string","maxLength":100},"target_duration":{"type":"number"},"style":{"type":"string","maxLength":50},"tone":{"type":"string","enum":["energetic","calm","confident","dramatic"]},"voice_speed":{"type":"number","minimum":0.7,"maximum":1.5},"music":{"type":"string","enum":["chill","energetic","corporate","dramatic","upbeat"]},"cta":{"type":"string","maxLength":100},"aspect_ratio":{"type":"string","enum":["9:16","16:9","1:1"]},"template":{"type":"string","maxLength":50},"composition_mode":{"type":"string","const":"pip"},"pip_options":{"type":"object","properties":{"position":{"type":"string","enum":["bottom-center","bottom-left","bottom-right"]},"size":{"type":"string","enum":["small","medium","large"]},"animation":{"type":"string","enum":["slide-up","slide-left","slide-right","fade","scale"]},"frame_style":{"type":"string","enum":["none","rounded","shadow"]}},"additionalProperties":false},"allow_broll":{"type":"boolean"},"broll_model":{"type":"string","enum":["kling3","hailuo2","wan21"]},"broll_images":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":10},"product_image_url":{"type":"string","format":"uri"},"dub_language":{"type":"string","maxLength":10},"webhook_url":{"type":"string","format":"uri"},"scenes":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["talking_head","broll"]}},"additionalProperties":true},"maxItems":30}},"additionalProperties":false}}}},"responses":{"201":{"description":"Job submitted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobSubmitted"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsufficientCredits"}}}},"429":{"description":"Rate limited","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/generate/product_review":{"post":{"operationId":"product_review","summary":"Generate a product review video from a product URL","tags":["generate"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"product_url":{"type":"string","format":"uri"},"angle":{"type":"string","enum":["honest","enthusiastic","roast","tutorial","comparison"]},"tone":{"type":"string","enum":["energetic","calm","confident","dramatic"]},"actor_slug":{"type":"string","minLength":1,"maxLength":100},"target_duration":{"type":"number"}},"required":["product_url"],"additionalProperties":false}}}},"responses":{"201":{"description":"Job submitted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobSubmitted"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsufficientCredits"}}}},"429":{"description":"Rate limited","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/generate/subtitle":{"post":{"operationId":"subtitle","summary":"Add styled subtitles to an existing video","tags":["generate"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"video_url":{"type":"string","format":"uri"},"style":{"type":"string","enum":["hormozi","minimal","bold","karaoke","clean","tiktok","neon","fire","glow","pop","aesthetic","impact","pastel","electric","boxed","gradient","spotlight"]}},"required":["video_url"],"additionalProperties":false}}}},"responses":{"201":{"description":"Job submitted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobSubmitted"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsufficientCredits"}}}},"429":{"description":"Rate limited","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/generate/show_your_app":{"post":{"operationId":"show_your_app","summary":"Generate a video showing your app with an AI actor holding a phone","tags":["generate"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_screenshot_url":{"type":"string","format":"uri"},"actor_slug":{"type":"string","minLength":1,"maxLength":100},"script":{"type":"string","minLength":5,"maxLength":3000},"duration":{"type":"number","default":5},"webhook_url":{"type":"string","format":"uri"}},"required":["app_screenshot_url","actor_slug","script"],"additionalProperties":false}}}},"responses":{"201":{"description":"Job submitted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobSubmitted"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsufficientCredits"}}}},"429":{"description":"Rate limited","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/actors":{"get":{"operationId":"listActors","summary":"List available actors","tags":["actors"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Actor list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActorList"}}}}}}},"/v1/videos/{jobId}":{"get":{"operationId":"getVideoStatus","summary":"Get video status","tags":["videos"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Job status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobStatus"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key (ma_xxx) or Supabase JWT"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object"}}},"required":["code","message"]}},"required":["error"]},"InsufficientCredits":{"type":"object","properties":{"error":{"type":"string"},"error_description":{"type":"string"},"credits_required":{"type":"integer"},"credits_available":{"type":"integer"}},"required":["error","credits_required","credits_available"]},"JobSubmitted":{"type":"object","properties":{"job_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["submitted"]},"estimated_duration":{"type":"integer"},"credits_deducted":{"type":"integer"},"selected_voice":{"type":"string"},"voice_auto_detected":{"type":"boolean"},"word_count":{"type":"integer"},"pacing_warning":{"type":"string","nullable":true}},"required":["job_id","status"]},"JobStatus":{"type":"object","properties":{"job_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["submitted","processing","completed","failed"]},"progress":{"type":"object"},"video_url":{"type":"string","format":"uri","nullable":true},"error_message":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["job_id","status"]},"ActorList":{"type":"object","properties":{"actors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"portrait_url":{"type":"string","format":"uri"},"age":{"type":"integer"},"gender":{"type":"string"},"nationality":{"type":"string"}}}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["actors","total"]}}}}