{"openapi":"3.1.0","info":{"title":"VidGuy Snacks API","version":"1.0.0","description":"Programmatic access to VidGuy snack generation. Register brands, kick off snack packs, optionally render to PNGs/MP4s server-side, and poll for completion.","license":{"name":"Proprietary","url":"https://www.vidguy.ai/terms"}},"servers":[{"url":"https://www.vidguy.ai"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"Send your API key in the Authorization header: \"Bearer vf_live_...\""}},"schemas":{"DirectorInput":{"type":"object","properties":{"version":{"type":"number","enum":[1]},"mode":{"type":"string","enum":["guide","locked"]},"creativeIntent":{"type":"string","minLength":1,"maxLength":2000},"visualDirection":{"type":"string","minLength":1,"maxLength":2000},"continuity":{"type":"string","minLength":1,"maxLength":2000},"avoid":{"type":"array","items":{"type":"string","minLength":1,"maxLength":500},"minItems":1,"maxItems":20},"scenes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":80,"pattern":"^[a-zA-Z0-9_-]+$"},"durationMs":{"type":"integer","exclusiveMinimum":0,"maximum":120000},"narration":{"type":"string","minLength":1,"maxLength":5000},"dialogue":{"type":"array","items":{"type":"object","properties":{"speaker":{"type":"string","minLength":1,"maxLength":80},"line":{"type":"string","minLength":1,"maxLength":1500}},"required":["speaker","line"],"additionalProperties":false},"minItems":1,"maxItems":10},"visualPrompt":{"type":"string","minLength":1,"maxLength":5000},"motionPrompt":{"type":"string","minLength":1,"maxLength":2000},"referenceAssetIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":5}},"required":["id","visualPrompt"],"additionalProperties":false},"minItems":1,"maxItems":20}},"required":["version","mode"],"additionalProperties":false,"description":"Optional, versioned creative/scene direction. Feature-gated; job-specific capabilities determine which fields and control modes can execute. Omit to retain existing generation behavior. Locked mode requires scenes with unique IDs; maximum 80,000 serialized characters."},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","example":"Invalid request"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["error"]},"ApiJobStatus":{"type":"string","enum":["queued","processing","awaiting_selection","completed","failed","cancelled"]},"VideoStatus":{"type":"string","enum":["draft","queued","script_generating","audio_processing","visual_processing","rendering","completed","failed","cancelled"]},"UgcActorPick":{"type":"object","properties":{"characterName":{"type":"string"},"imageUrl":{"type":"string"},"picker":{"type":"string","enum":["jev-image","jev","tags_fallback"],"description":"jev-image = the picker looked at the shortlisted photos and chose one; jev = semantic pick from the photos' descriptions; tags_fallback = demographic + tag match (used when the semantic picker is unavailable or no photo fit well enough)."},"fit":{"type":["number","null"],"description":"How well the photo fits the script, 0..1 (jev / jev-image only; picks below 0.3 fall back to tags)."},"setting":{"type":"string","example":"train-interior"},"settingGroup":{"type":"string","example":"transit"},"libraryAssetId":{"type":"string"}},"required":["characterName","imageUrl","picker","fit","setting","settingGroup","libraryAssetId"],"description":"How an auto actor was chosen. Returned only when the request sent ugc.characterId \"auto\"."},"UgcSettings":{"type":"object","properties":{"characterId":{"type":"string","minLength":1,"description":"A saved actor id (list_characters / POST /api/v1/characters), or \"auto\" to let VidGuy pick a talking-head actor whose setting, gender and age fit the script, topic and scenePrompt. The auto pick is saved as a character on your account (free) and its id comes back as characterId on the create response and on every poll — pass that id on later videos to keep the same actor across a campaign.","example":"auto"},"scenePrompt":{"type":"string","minLength":5,"maxLength":500},"sceneImageUrl":{"type":"string","format":"uri"},"demoVideoUrl":{"type":"string","format":"uri"},"script":{"type":"string","minLength":10,"maxLength":5000},"engine":{"type":"string","enum":["pvideo2","h3ultra"],"default":"pvideo2"},"dubbing":{"type":"object","properties":{"enabled":{"type":"boolean","default":false},"voice":{"anyOf":[{"type":"string","enum":["auto","male-professional","male-casual","female-professional","female-casual","dramatic"]},{"type":"string","pattern":"^[A-Za-z0-9_-]{10,}$"}],"default":"auto"}},"default":{"enabled":false,"voice":"auto"}}},"required":["characterId","script"],"description":"UGC (talking-head) settings. Required for videoType ugc, brainrot, ugc-broll and ugc-demo."},"LegacyVideoBrief":{"type":"object","properties":{"directorInput":{"$ref":"#/components/schemas/DirectorInput"},"topic":{"type":"string","minLength":3,"maxLength":500},"durationSeconds":{"type":"integer","minimum":15,"maximum":60},"platform":{"type":"string","enum":["tiktok","reels","shorts","youtube","linkedin"]},"videoType":{"type":"string","enum":["faceless","motion-graphics","whiteboard","ugc","brainrot","ugc-broll","ugc-demo"]},"ugc":{"$ref":"#/components/schemas/UgcSettings"},"tone":{"type":"string","maxLength":100},"voicePreference":{"type":"object","properties":{"gender":{"type":"string"},"style":{"type":"string"},"voiceId":{"type":"string"}}},"brandColors":{"type":"object","properties":{"primary":{"type":"string"},"secondary":{"type":"string"},"accent":{"type":"string"}}},"hookType":{"type":"string","maxLength":50},"visualStyle":{"type":"string","maxLength":100},"additionalInstructions":{"type":"string","maxLength":1000},"templateId":{"type":"string","maxLength":50}},"required":["topic","durationSeconds","platform"]},"CreateVideoRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"brief":{"$ref":"#/components/schemas/LegacyVideoBrief"}},"required":["brief"]},"CreateVideoResponse":{"type":"object","properties":{"id":{"type":["string","null"]},"status":{"type":"string"},"creditsUsed":{"type":"integer"},"characterId":{"type":"string","description":"Only when ugc.characterId was \"auto\": the actor that was picked. Reuse it on later videos."},"actorPick":{"$ref":"#/components/schemas/UgcActorPick"}},"required":["id","status","creditsUsed"]},"ListVideoItem":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"$ref":"#/components/schemas/VideoStatus"},"progress":{"type":"integer"},"outputUrl":{"type":["string","null"]},"creditsUsed":{"type":"integer"},"errorMessage":{"type":["string","null"]},"createdAt":{"type":"string"},"completedAt":{"type":["string","null"]}},"required":["id","name","status","progress","outputUrl","creditsUsed","errorMessage","createdAt","completedAt"]},"ListVideosResponse":{"type":"object","properties":{"videos":{"type":"array","items":{"$ref":"#/components/schemas/ListVideoItem"}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["total","limit","offset"]}},"required":["videos","pagination"]},"VideoDetailResponse":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"$ref":"#/components/schemas/VideoStatus"},"progress":{"type":"integer"},"outputUrl":{"type":["string","null"]},"creditsUsed":{"type":"integer"},"errorMessage":{"type":["string","null"]},"revisionsCount":{"type":"integer"},"createdAt":{"type":"string"},"startedAt":{"type":["string","null"]},"completedAt":{"type":["string","null"]},"brief":{"type":["object","null"],"properties":{"directorInput":{"$ref":"#/components/schemas/DirectorInput"},"topic":{"type":"string"},"durationSeconds":{"type":"integer"},"platform":{"type":"string"},"tone":{"type":["string","null"]},"hookType":{"type":["string","null"]},"visualStyle":{"type":["string","null"]},"videoType":{"type":["string","null"]},"characterId":{"type":"string","description":"UGC videos: the actor id used (the picked one when the request sent \"auto\")."},"actorPick":{"type":"object","properties":{"picker":{"type":"string","enum":["jev-image","jev","tags_fallback"],"description":"jev-image = the picker looked at the shortlisted photos and chose one; jev = semantic pick from the photos' descriptions; tags_fallback = demographic + tag match (used when the semantic picker is unavailable or no photo fit well enough)."},"fit":{"type":["number","null"],"description":"How well the photo fits the script, 0..1 (jev / jev-image only; picks below 0.3 fall back to tags)."},"setting":{"type":"string","example":"train-interior"},"settingGroup":{"type":"string","example":"transit"},"libraryAssetId":{"type":"string"}},"required":["picker","fit","setting","settingGroup","libraryAssetId"],"description":"UGC auto actor only: how the actor was chosen."}},"required":["topic","durationSeconds","platform","tone","hookType","visualStyle"]},"carousel":{"type":["object","null"],"properties":{"slides":{"type":"array","items":{"type":"object","properties":{"assetId":{"type":"string"},"slot":{"type":"integer"},"revision":{"type":"integer"},"outputUrl":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["assetId","slot","revision","outputUrl","createdAt"]}}},"required":["slides"]},"slides":{"type":["object","null"],"properties":{"slides":{"type":"array","items":{"type":"object","properties":{"assetId":{"type":"string"},"slot":{"type":"integer"},"revision":{"type":"integer"},"outputUrl":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["assetId","slot","revision","outputUrl","createdAt"]}}},"required":["slides"]},"assets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"fileSizeBytes":{"type":["integer","null"]},"durationMs":{"type":["integer","null"]},"createdAt":{"type":"string"}},"required":["id","type","fileSizeBytes","durationMs","createdAt"]}}},"required":["id","name","status","progress","outputUrl","creditsUsed","errorMessage","revisionsCount","createdAt","startedAt","completedAt","brief","carousel","slides","assets"]},"CancelVideoResponse":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["cancelled"]},"creditsRefunded":{"type":"integer"}},"required":["id","status","creditsRefunded"]},"CreateVideoJobRequest":{"type":"object","properties":{"offeringId":{"type":"string","enum":["video_production"]},"name":{"type":"string","minLength":1,"maxLength":200},"input":{"type":"object","properties":{"directorInput":{"type":"object","properties":{"version":{"type":"number","enum":[1]},"mode":{"type":"string","enum":["guide","locked"]},"creativeIntent":{"type":"string","minLength":1,"maxLength":2000},"visualDirection":{"type":"string","minLength":1,"maxLength":2000},"continuity":{"type":"string","minLength":1,"maxLength":2000},"avoid":{"type":"array","items":{"type":"string","minLength":1,"maxLength":500},"minItems":1,"maxItems":20},"scenes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":80,"pattern":"^[a-zA-Z0-9_-]+$"},"durationMs":{"type":"integer","exclusiveMinimum":0,"maximum":120000},"narration":{"type":"string","minLength":1,"maxLength":5000},"dialogue":{"type":"array","items":{"type":"object","properties":{"speaker":{"type":"string","minLength":1,"maxLength":80},"line":{"type":"string","minLength":1,"maxLength":1500}},"required":["speaker","line"],"additionalProperties":false},"minItems":1,"maxItems":10},"visualPrompt":{"type":"string","minLength":1,"maxLength":5000},"motionPrompt":{"type":"string","minLength":1,"maxLength":2000},"referenceAssetIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":5}},"required":["id","visualPrompt"],"additionalProperties":false},"minItems":1,"maxItems":20}},"required":["version","mode"],"additionalProperties":false},"topic":{"type":"string","minLength":3,"maxLength":5000},"durationSeconds":{"anyOf":[{"type":"number","enum":[10]},{"type":"number","enum":[15]},{"type":"number","enum":[30]},{"type":"number","enum":[45]},{"type":"number","enum":[60]}]},"platform":{"type":"string","enum":["tiktok","reels","shorts","youtube","linkedin"]},"templateId":{"type":"string","maxLength":100},"videoType":{"type":"string","enum":["faceless","motion-graphics","whiteboard","ugc","brainrot","ugc-broll","ugc-demo"]},"ugc":{"$ref":"#/components/schemas/UgcSettings"},"contentSources":{"type":"object","properties":{"preset":{"type":"string","enum":["eco","balanced","premium","custom"],"default":"balanced"},"stockMedia":{"type":"boolean","default":true},"aiImages":{"type":"boolean","default":true},"aiVideos":{"type":"boolean","default":false},"motionGraphics":{"type":"boolean","default":false},"youtubeClips":{"type":"boolean","default":false},"maxAiImages":{"type":"integer","minimum":0,"maximum":10,"default":10},"maxAiVideos":{"type":"integer","minimum":0,"maximum":10,"default":10}}},"audio":{"type":"object","properties":{"voiceover":{"type":"object","properties":{"enabled":{"type":"boolean","default":true},"voice":{"anyOf":[{"type":"string","enum":["auto","male-professional","male-casual","female-professional","female-casual","dramatic"]},{"type":"string","pattern":"^[A-Za-z0-9_-]{10,}$"}],"default":"auto"}},"default":{"enabled":true,"voice":"auto"}},"music":{"type":"object","properties":{"enabled":{"type":"boolean","default":true},"mood":{"type":"string","enum":["auto","epic","uplifting","dark","energetic","calm","none"],"default":"auto"},"source":{"type":"string","enum":["ai-generated","seed-audio","stock","none"],"default":"ai-generated"}},"default":{"enabled":true,"mood":"auto","source":"ai-generated"}},"captions":{"type":"object","properties":{"enabled":{"type":"boolean","default":true},"style":{"type":"string","enum":["default","bold","minimal","animated","tiktok"],"default":"default"},"template":{"type":"string","enum":["basic","classic","hustle","minimal","neon","handwritten","cinematic"]},"aiEditStyle":{"type":"string","enum":["bloom","prism","slam","lava","editorial","parallax","matrix","highlight","clipwipe"]},"fontSizeScale":{"type":"number","minimum":0.5,"maximum":2}},"default":{"enabled":true,"style":"default"}},"soundEffects":{"type":"object","properties":{"enabled":{"type":"boolean","default":false}},"default":{"enabled":false}}}},"style":{"type":"object","properties":{"tone":{"type":"string","enum":["auto","professional","casual","humorous","inspirational","educational","dramatic","energetic"],"default":"auto"},"visualStyle":{"type":"string","enum":["auto","cinematic","minimal","bold","tech","organic","retro","chalkboard","whiteboard"],"default":"auto"},"hookType":{"type":"string","enum":["auto","question","statistic","bold-claim","story","visual-shock","challenge"],"default":"auto"},"renderStyle":{"type":"string","enum":["photoreal","cinematic","cartoon","anime","pixel-art","watercolor","3d-render","claymation"]}}},"brand":{"type":"object","properties":{"name":{"type":"string","maxLength":100},"logoUrl":{"type":"string","maxLength":2000,"format":"uri"},"colors":{"type":"object","properties":{"primary":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"secondary":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"accent":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"background":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"text":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"}}},"typography":{"type":"object","properties":{"heading":{"type":"string","maxLength":120},"body":{"type":"string","maxLength":120}}},"voice":{"type":"string","maxLength":1500},"visualStyle":{"type":"string","maxLength":1500},"usage":{"type":"object","properties":{"do":{"type":"string","maxLength":1500},"avoid":{"type":"string","maxLength":1500}}},"useBrandKit":{"type":"boolean"},"source":{"type":"string","enum":["company-brain","brief"]}}},"additionalInstructions":{"type":"string","maxLength":500}},"required":["topic","durationSeconds","platform","videoType"]}},"required":["offeringId","input"]},"CreateClipAnalysisJobRequest":{"type":"object","properties":{"offeringId":{"type":"string","enum":["clip_analysis_upload"]},"name":{"type":"string","minLength":1,"maxLength":200},"input":{"type":"object","properties":{"r2Key":{"type":"string","minLength":1,"maxLength":500},"fileName":{"type":"string","minLength":1,"maxLength":255},"fileSize":{"type":"integer","exclusiveMinimum":0},"contentType":{"type":"string","minLength":1,"maxLength":100},"preferences":{"type":"object","properties":{"clipCount":{"type":"integer","minimum":1,"maximum":10},"maxClipSeconds":{"type":"integer","minimum":10,"maximum":120},"hookFocus":{"type":"string","enum":["big-reveals","high-energy","concise-explainers","surprise-moments","story-payoff"]},"notes":{"type":"string","maxLength":1000}},"required":["clipCount","maxClipSeconds","hookFocus"]},"aiModel":{"type":"string","enum":["standard","experimental"]}},"required":["r2Key","fileName","preferences"]}},"required":["offeringId","input"]},"CreateClipRenderJobRequest":{"type":"object","properties":{"offeringId":{"type":"string","enum":["clip_render"]},"name":{"type":"string","minLength":1,"maxLength":200},"input":{"type":"object","properties":{"analysisJobId":{"type":"string","format":"uuid"},"candidateIds":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":10}},"required":["analysisJobId","candidateIds"]}},"required":["offeringId","input"]},"CreateApiJobRequest":{"anyOf":[{"$ref":"#/components/schemas/CreateVideoJobRequest"},{"$ref":"#/components/schemas/CreateClipAnalysisJobRequest"},{"$ref":"#/components/schemas/CreateClipRenderJobRequest"}]},"CreateApiJobResponse":{"type":"object","properties":{"jobId":{"type":"string"},"offeringId":{"type":"string","enum":["video_production","clip_analysis_upload","clip_render","snack_generation","ai_story_generation","carousel_generation","slides_generation","carousel_v2_batch"]},"projectId":{"type":"string"},"clipJobId":{"type":"string"},"status":{"$ref":"#/components/schemas/ApiJobStatus"},"pollUrl":{"type":"string"},"instanceId":{"type":["string","null"]},"creditsReserved":{"type":"integer"},"characterId":{"type":"string","description":"video_production with ugc.characterId \"auto\": the actor that was picked (also in result.characterId on every poll). Reuse it on later videos."},"actorPick":{"$ref":"#/components/schemas/UgcActorPick"}},"required":["jobId","offeringId","status","pollUrl"]},"GetApiJobResponse":{"type":"object","properties":{"jobId":{"type":"string"},"offeringId":{"type":"string","enum":["video_production","clip_analysis_upload","clip_render","snack_generation","ai_story_generation","carousel_generation","slides_generation","carousel_v2_batch"]},"name":{"type":["string","null"]},"status":{"$ref":"#/components/schemas/ApiJobStatus"},"progress":{"type":"integer"},"projectId":{"type":["string","null"]},"clipJobId":{"type":["string","null"]},"parentJobId":{"type":["string","null"]},"instanceId":{"type":["string","null"]},"creditsReserved":{"type":["integer","null"]},"creditsFinal":{"type":["integer","null"]},"error":{"type":["string","null"]},"result":{"type":"object","additionalProperties":{}},"createdAt":{"type":["string","null"]},"updatedAt":{"type":["string","null"]}},"required":["jobId","offeringId","status","progress","result"]},"CreditsResponse":{"type":"object","properties":{"balance":{"type":"integer"},"plan":{"type":["object","null"],"properties":{"type":{"type":"string"},"creditsIncluded":{"type":"integer"},"creditsUsedThisPeriod":{"type":"integer"},"periodStart":{"type":["string","null"]},"periodEnd":{"type":["string","null"]}},"required":["type","creditsIncluded","creditsUsedThisPeriod","periodStart","periodEnd"]},"recentTransactions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"integer"},"type":{"type":"string"},"description":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","amount","type","description","createdAt"]}}},"required":["balance","plan","recentTransactions"]},"Offering":{"type":"object","properties":{"id":{"type":"string","enum":["video_production","clip_analysis_upload","clip_render","snack_generation","ai_story_generation","carousel_generation","slides_generation","carousel_v2_batch"]},"name":{"type":"string"},"description":{"type":"string"},"async":{"type":"boolean"},"inputSchema":{"type":"object","additionalProperties":{}},"creditPolicy":{"type":"string"},"resultShape":{"type":"object","additionalProperties":{}}},"required":["id","name","description","async","inputSchema","creditPolicy","resultShape"]},"OfferingsResponse":{"type":"object","properties":{"offerings":{"type":"array","items":{"$ref":"#/components/schemas/Offering"}}},"required":["offerings"]},"Template":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"bestFor":{"type":"array","items":{"type":"string"}},"platforms":{"type":"array","items":{"type":"string"}},"scenes":{"type":"object","properties":{"min":{"type":"integer"},"max":{"type":"integer"}},"required":["min","max"]}},"required":["id","name","description","bestFor","platforms","scenes"]},"TemplatesResponse":{"type":"object","properties":{"templates":{"type":"array","items":{"$ref":"#/components/schemas/Template"}},"briefSchema":{"type":"object","additionalProperties":{"type":"object","properties":{"type":{"type":"string"},"required":{"type":"boolean"},"minLength":{"type":"integer"},"maxLength":{"type":"integer"},"enum":{"type":"array","items":{"type":"string"}},"description":{"type":"string"},"properties":{"type":"object","additionalProperties":{}}}}}},"required":["templates","briefSchema"]},"UploadRequest":{"type":"object","properties":{"fileName":{"type":"string","minLength":1,"maxLength":255},"fileType":{"type":"string","minLength":1,"maxLength":100},"fileSize":{"type":"integer","exclusiveMinimum":0}},"required":["fileName","fileType","fileSize"]},"UploadResponse":{"type":"object","properties":{"uploadUrl":{"type":"string"},"r2Key":{"type":"string"},"fileType":{"type":"string"},"fileSize":{"type":"integer"},"maxSizeBytes":{"type":"integer"},"expiresInSeconds":{"type":"integer"}},"required":["uploadUrl","r2Key","fileType","fileSize","maxSizeBytes","expiresInSeconds"]},"CreditsTopupOffer":{"type":"object","properties":{"credits":{"type":"integer"},"priceUsd":{"type":"string"},"url":{"type":"string"}},"required":["credits","priceUsd","url"]},"CreditsTopupRails":{"type":"object","properties":{"x402":{"type":"boolean"},"mpp":{"type":"boolean"}},"required":["x402","mpp"]},"CreditsTopupOffersResponse":{"type":"object","properties":{"enabled":{"type":"boolean"},"rails":{"$ref":"#/components/schemas/CreditsTopupRails"},"usdPerCredit":{"type":"number"},"offers":{"type":"array","items":{"$ref":"#/components/schemas/CreditsTopupOffer"}},"suggestedCredits":{"type":["integer","null"]},"how":{"type":"string"}},"required":["enabled","rails","usdPerCredit","offers","suggestedCredits","how"]},"CreditsTopupPaymentRequired":{"type":"object","properties":{"error":{"type":"string","enum":["payment_required"]},"credits":{"type":"integer"},"amountUsd":{"type":"string"},"rails":{"type":"array","items":{"type":"string","enum":["x402","mpp"]}},"message":{"type":"string"},"offers":{"type":"array","items":{"$ref":"#/components/schemas/CreditsTopupOffer"}}},"required":["error","credits","amountUsd","rails","message","offers"]},"CreditsTopupResponse":{"type":"object","properties":{"creditsAdded":{"type":"integer"},"newBalance":{"type":"integer"},"duplicate":{"type":"boolean"},"rail":{"type":"string","enum":["x402","mpp"]},"reference":{"type":"string"},"network":{"type":"string"},"method":{"type":"string"},"amountUsd":{"type":"string"}},"required":["creditsAdded","newBalance","duplicate","rail","reference","amountUsd"]},"AgentRegisterRequest":{"type":"object","properties":{"operatorEmail":{"type":"string","format":"email"},"operatorName":{"type":"string"},"billingCountry":{"type":"string","minLength":2,"maxLength":2},"vatId":{"type":"string"},"acceptTerms":{"type":"boolean","enum":[true]},"agentName":{"type":"string"}},"required":["operatorEmail","billingCountry","acceptTerms"]},"AgentRegisterResponse":{"type":"object","properties":{"userId":{"type":"string"},"plan":{"type":"string","enum":["agent"]},"credits":{"type":"integer"},"apiKey":{"type":"string"},"apiKeyNote":{"type":"string"},"topup":{"type":"object","properties":{"offersUrl":{"type":"string"},"offers":{"type":"array","items":{"$ref":"#/components/schemas/CreditsTopupOffer"}},"rails":{"$ref":"#/components/schemas/CreditsTopupRails"}},"required":["offersUrl","offers","rails"]},"endpoints":{"type":"object","properties":{"mcp":{"type":"string"},"openapi":{"type":"string"},"pricing":{"type":"string"},"credits":{"type":"string"}},"required":["mcp","openapi","pricing","credits"]},"retention":{"type":"string"},"termsVersion":{"type":"string"}},"required":["userId","plan","credits","apiKey","apiKeyNote","topup","endpoints","retention","termsVersion"]},"SnackBrand":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"industry":{"type":"string"},"description":{"type":"string"},"targetAudience":{"type":"string"},"websiteUrl":{"type":["string","null"]},"logoUrl":{"type":["string","null"]},"appDemo":{"type":["string","null"],"description":"Deprecated — first entry of appDemos, kept for back-compat"},"appDemos":{"type":"array","items":{"type":"string"},"description":"Demo video URLs. The broll-demo snack picks one at random per generation."},"screenshots":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","industry","description","targetAudience","websiteUrl","logoUrl","appDemo","appDemos","screenshots","createdAt","updatedAt"]},"CreateSnackBrandRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","minLength":30,"maxLength":2000},"industry":{"type":"string","minLength":1,"maxLength":100},"targetAudience":{"type":"string","minLength":1,"maxLength":1000},"websiteUrl":{"type":"string","maxLength":500,"format":"uri"},"logoUrl":{"type":"string","maxLength":500,"format":"uri"},"appDemo":{"type":"string","maxLength":500,"format":"uri","description":"Deprecated — single demo URL; prefer appDemos"},"appDemos":{"type":"array","items":{"type":"string","maxLength":500,"format":"uri"},"maxItems":10},"screenshots":{"type":"array","items":{"type":"string","maxLength":500,"format":"uri"},"maxItems":10}},"required":["name","description","industry"]},"UpdateSnackBrandRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","minLength":30,"maxLength":2000},"industry":{"type":"string","minLength":1,"maxLength":100},"targetAudience":{"type":"string","minLength":1,"maxLength":1000},"websiteUrl":{"type":["string","null"],"maxLength":500,"format":"uri"},"logoUrl":{"type":["string","null"],"maxLength":500,"format":"uri"},"appDemo":{"type":["string","null"],"maxLength":500,"format":"uri","description":"Deprecated — single demo URL; prefer appDemos"},"appDemos":{"type":["array","null"],"items":{"type":"string","maxLength":500,"format":"uri"},"maxItems":10},"screenshots":{"type":"array","items":{"type":"string","maxLength":500,"format":"uri"},"maxItems":10}}},"SnackBrandsListResponse":{"type":"object","properties":{"brands":{"type":"array","items":{"$ref":"#/components/schemas/SnackBrand"}},"pagination":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["limit","offset"]}},"required":["brands","pagination"]},"SnackPostManifest":{"type":"object","properties":{"version":{"type":"number","enum":[1]},"aspectRatio":{"type":"string","enum":["9:16","1:1","16:9"]},"snacks":{"type":"array","items":{"type":"object","additionalProperties":{}}}},"required":["version","aspectRatio","snacks"],"description":"Render-agnostic JSON description of a snack post. Each `snacks[]` entry contains scenes, visual URLs, text overlays, and audio."},"SnackPost":{"type":"object","properties":{"id":{"type":"string"},"brandId":{"type":["string","null"]},"name":{"type":"string"},"status":{"type":"string"},"manifest":{"$ref":"#/components/schemas/SnackPostManifest"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","brandId","name","status","manifest","createdAt","updatedAt"]},"SnacksListResponse":{"type":"object","properties":{"snacks":{"type":"array","items":{"$ref":"#/components/schemas/SnackPost"}},"pagination":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["limit","offset"]}},"required":["snacks","pagination"]},"CreateSnackRequest":{"type":"object","properties":{"brandId":{"type":"string","format":"uuid","example":"b7f3a8b2-1234-5678-9abc-def012345678"},"name":{"type":"string","minLength":1,"maxLength":200},"callbackUrl":{"type":"string","maxLength":500,"format":"uri"},"render":{"type":"boolean","description":"When true, also render PNGs/MP4s server-side. Adds +3 credits. URLs land in result.renderedAssets[]."},"exclude":{"type":"array","items":{"type":"string","enum":["slides","text-wall","ai-ugc","broll-demo","greenscreen-meme","meme-edit","single-image","sticker-pack","static-ad","ugc-ad","animated-ad","greenscreen-ad","music-ad"]},"maxItems":13,"description":"Snack types to skip. Still supported with `types`; exclusions are subtracted after the allow-list is applied."},"types":{"type":"array","items":{"type":"string","enum":["slides","text-wall","ai-ugc","broll-demo","greenscreen-meme","meme-edit","single-image","sticker-pack","static-ad","ugc-ad","animated-ad","greenscreen-ad","music-ad"]},"minItems":1,"maxItems":13,"description":"Positive snack-type allow-list. Use with `count` for packs like 5 greenscreen memes or 5 slide carousels."},"count":{"type":"integer","minimum":1,"maximum":5,"description":"Total snacks to request. When `types` has one value, all requested snacks use that type.","example":5},"context":{"type":"string","maxLength":20000,"description":"Per-request creative steer woven into the snack copy and asset selection."},"prompt":{"type":"string","maxLength":20000,"description":"Alias for `context`."}},"required":["brandId"]},"CreateSnackResponse":{"type":"object","properties":{"jobId":{"type":"string"},"offeringId":{"type":"string","enum":["snack_generation"]},"status":{"$ref":"#/components/schemas/ApiJobStatus"},"pollUrl":{"type":"string"},"instanceId":{"type":["string","null"]},"creditsReserved":{"type":"integer"},"render":{"type":"boolean"},"exclude":{"type":"array","items":{"type":"string","enum":["slides","text-wall","ai-ugc","broll-demo","greenscreen-meme","meme-edit","single-image","sticker-pack","static-ad","ugc-ad","animated-ad","greenscreen-ad","music-ad"]}},"types":{"type":"array","items":{"type":"string","enum":["slides","text-wall","ai-ugc","broll-demo","greenscreen-meme","meme-edit","single-image","sticker-pack","static-ad","ugc-ad","animated-ad","greenscreen-ad","music-ad"]}},"count":{"type":"integer"},"snackTypeSequence":{"type":"array","items":{"type":"string","enum":["slides","text-wall","ai-ugc","broll-demo","greenscreen-meme","meme-edit","single-image","sticker-pack","static-ad","ugc-ad","animated-ad","greenscreen-ad","music-ad"]}}},"required":["jobId","offeringId","status","pollUrl","creditsReserved"]},"CreateOnDemandSnackRequest":{"type":"object","properties":{"shopUrl":{"type":"string","description":"Store, product page, service site or app listing to make ads from.","example":"https://drinkolipop.com"},"types":{"type":"array","items":{"type":"string","enum":["static-ad","ugc-ad","animated-ad","greenscreen-ad","music-ad"]},"minItems":1,"description":"Ad types to make. Omit for the default pack.","example":["music-ad"]},"count":{"type":"integer","minimum":1,"maximum":5,"description":"Number of ads (1-5)."},"prompt":{"type":"string","maxLength":4000,"description":"Creative steer for every ad (theme, audience, genre, look).","example":"Halloween party theme"},"language":{"type":"string","enum":["en","es","fr","de","it","pt","nl","pl","sq","tr","ru","ar","hi","id","vi","th","ja","ko","zh"],"description":"Language of the ads (ISO 639-1). Default `en`.","example":"es"},"adAspectRatio":{"type":"string","enum":["4:5","1:1","9:16"],"description":"Static-ad frame. Default `4:5`."},"adFormats":{"type":"array","items":{"type":"string","enum":["review_card","us_vs_them","benefit_callouts","platform_native","offer_stack","problem_solution","reasons_listicle","ugc_photo","social_proof_stat","press_bar","product_hero","service_hero"]},"minItems":1,"description":"Static-ad layouts to use, in order."},"animationStyle":{"type":"string","enum":["claymation","pixar_3d","felt_stop_motion","cartoon_2d"],"description":"Animated-ad look."},"presenterImageUrl":{"type":"string","maxLength":2000,"format":"uri","description":"Ads only: a photo of the person (or character) to feature instead of a stock presenter. Talking ads film them, animated and music ads draw them in the film's style, and each static ad decides how to show them. At least 256px on the short side.","example":"https://example.com/presenter.jpg"},"websiteUrl":{"type":"string","description":"Website mode (Scale): a snack pack from a website."},"dexScreenerUrl":{"type":"string","description":"Token mode (Scale): a snack pack from a DexScreener pair."},"render":{"type":"boolean","description":"Render PNG / MP4 files (+1 credit for ads, +3 for snack packs)."},"name":{"type":"string","minLength":1,"maxLength":200}}},"CreateOnDemandSnackResponse":{"type":"object","properties":{"jobId":{"type":"string"},"offeringId":{"type":"string","enum":["snack_generation"]},"status":{"$ref":"#/components/schemas/ApiJobStatus"},"pollUrl":{"type":"string"},"creditsReserved":{"type":"integer","example":76},"render":{"type":"boolean","example":true},"types":{"type":"array","items":{"type":"string","enum":["slides","text-wall","ai-ugc","broll-demo","greenscreen-meme","meme-edit","single-image","sticker-pack","static-ad","ugc-ad","animated-ad","greenscreen-ad","music-ad"]},"example":["music-ad"]},"count":{"type":"integer","example":1},"snackTypeSequence":{"type":"array","items":{"type":"string","enum":["slides","text-wall","ai-ugc","broll-demo","greenscreen-meme","meme-edit","single-image","sticker-pack","static-ad","ugc-ad","animated-ad","greenscreen-ad","music-ad"]},"example":["music-ad"]},"source":{"type":"string","enum":["shop","website","token"],"example":"shop"}},"required":["jobId","offeringId","status","pollUrl","creditsReserved"]},"CreateMemeRequest":{"type":"object","properties":{"memeType":{"type":"string","enum":["meme-edit","meme-greenscreen","meme-comic"],"description":"Meme format: reaction-clip caption rewrite, keyed greenscreen reaction, or illustrated comic strip."},"prompt":{"type":"string","minLength":3,"maxLength":2000,"description":"Plain-language subject or moment to turn into a meme; the caller does not need to write the joke.","example":"When the AI video renders perfectly on the first try"},"count":{"type":"integer","minimum":1,"maximum":5,"description":"Number of variations of the selected type (default 1).","example":1},"brandId":{"type":"string","description":"Optional tenant brand UUID. Omit for brandless prompt-only generation."}},"required":["memeType","prompt"]},"CreateMemeResponse":{"type":"object","properties":{"jobId":{"type":"string"},"offeringId":{"type":"string","enum":["meme_snack_pack"]},"status":{"$ref":"#/components/schemas/ApiJobStatus"},"pollUrl":{"type":"string"},"creditsReserved":{"type":"integer"},"count":{"type":"integer"},"memeType":{"type":"string","enum":["meme-edit","meme-greenscreen","meme-comic"]}},"required":["jobId","offeringId","status","pollUrl","creditsReserved","count","memeType"]},"CreateAiStoryRequest":{"type":"object","properties":{"directorInput":{"$ref":"#/components/schemas/DirectorInput"},"prompt":{"type":"string","minLength":10,"maxLength":5000},"referenceImageUrl":{"type":"string","format":"uri"},"styleTemplateId":{"type":"string","enum":["fruit-drama","toy-soap","claymotion","anime-romance","educational-explainer","custom"]},"styleReferenceImageUrl":{"type":"string","format":"uri"},"duration":{"type":"string","enum":["short","medium"]},"engine":{"type":"string","enum":["grok"]},"platform":{"type":"string","enum":["tiktok","reels","shorts","youtube","linkedin"]},"topic":{"type":"string","minLength":3,"maxLength":5000},"name":{"type":"string","minLength":1,"maxLength":200}},"required":["prompt","referenceImageUrl"]},"CreateAiStoryResponse":{"type":"object","properties":{"jobId":{"type":"string"},"offeringId":{"type":"string","enum":["ai_story_generation"]},"projectId":{"type":"string"},"status":{"$ref":"#/components/schemas/ApiJobStatus"},"pollUrl":{"type":"string"},"instanceId":{"type":["string","null"]},"creditsReserved":{"type":"integer"},"duration":{"type":"string","enum":["short","medium"]},"sceneCount":{"type":"integer"}},"required":["jobId","offeringId","projectId","status","pollUrl","creditsReserved","duration","sceneCount"]},"CreateCarouselRequest":{"type":"object","properties":{"prompt":{"type":"string","minLength":3,"maxLength":5000},"referenceImageUrl":{"type":"string","format":"uri"},"platform":{"type":"string","enum":["tiktok","reels","shorts","youtube","linkedin"]},"topic":{"type":"string","minLength":3,"maxLength":5000},"name":{"type":"string","minLength":1,"maxLength":200}},"required":["prompt","referenceImageUrl"]},"CreateCarouselResponse":{"type":"object","properties":{"jobId":{"type":"string"},"offeringId":{"type":"string","enum":["carousel_generation"]},"projectId":{"type":"string"},"status":{"$ref":"#/components/schemas/ApiJobStatus"},"pollUrl":{"type":"string"},"instanceId":{"type":["string","null"]},"creditsReserved":{"type":"integer"}},"required":["jobId","offeringId","projectId","status","pollUrl","creditsReserved"]},"CreateSlidesRequest":{"type":"object","properties":{"prompt":{"type":"string","minLength":3,"maxLength":5000},"referenceImageUrl":{"type":"string","format":"uri"},"platform":{"type":"string","enum":["tiktok","reels","shorts","youtube","linkedin"]},"topic":{"type":"string","minLength":3,"maxLength":5000},"name":{"type":"string","minLength":1,"maxLength":200}},"required":["prompt","referenceImageUrl"]},"CreateSlidesResponse":{"type":"object","properties":{"jobId":{"type":"string"},"offeringId":{"type":"string","enum":["slides_generation"]},"projectId":{"type":"string"},"status":{"$ref":"#/components/schemas/ApiJobStatus"},"pollUrl":{"type":"string"},"instanceId":{"type":["string","null"]},"creditsReserved":{"type":"integer"}},"required":["jobId","offeringId","projectId","status","pollUrl","creditsReserved"]},"CarouselV2TemplatesResponse":{"type":"object","properties":{"maxRowsPerCall":{"type":"integer"},"templates":{"type":"array","items":{"type":"object","properties":{"templateKey":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"slides":{"type":"integer"},"thumbnailUrl":{"type":["string","null"]},"rowSchema":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"type":{"type":"string","enum":["text","image"]},"label":{"type":"string"},"page":{"type":"integer"},"example":{"type":"string"}},"required":["key","type","label","page","example"]}}},"required":["templateKey","name","description","slides","rowSchema"]}}},"required":["maxRowsPerCall","templates"]},"CreateCarouselV2Request":{"type":"object","properties":{"templateKey":{"type":"string","minLength":1,"maxLength":120,"description":"Built-in slug (e.g. `story-4`) or the uuid of one of your saved templates."},"rows":{"type":"array","items":{"type":"object","properties":{"values":{"type":"object","additionalProperties":{"type":"string","maxLength":2000},"description":"Keyed by the template's variable keys, from GET /api/v1/carousel-v2/templates. Unknown keys are dropped and returned in `ignoredKeys`."},"caption":{"type":"string","maxLength":3000}},"required":["values"]},"minItems":1,"maxItems":12,"description":"One carousel per entry."},"name":{"type":"string","minLength":1,"maxLength":120},"seed":{"type":"string","minLength":1,"maxLength":80,"description":"Fixes collection photo picks so the same input reproduces the same slides."},"noRepeatScope":{"type":"string","enum":["row","batch"]}},"required":["templateKey","rows"]},"CreateCarouselV2Response":{"type":"object","properties":{"jobId":{"type":"string"},"offeringId":{"type":"string","enum":["carousel_v2_batch"]},"batchId":{"type":"string"},"status":{"$ref":"#/components/schemas/ApiJobStatus"},"pollUrl":{"type":"string"},"creditsReserved":{"type":"integer"},"carousels":{"type":"integer"},"noRepeatScope":{"type":"string","enum":["row","batch"]},"ignoredKeys":{"type":"array","items":{"type":"string"},"description":"Row keys that are not variables on this template. Reported, not rejected."}},"required":["jobId","offeringId","batchId","status","pollUrl","creditsReserved","carousels","noRepeatScope"]},"StudioGenerateRequest":{"type":"object","properties":{"mode":{"type":"string","enum":["image","video","audio"]},"modelKey":{"type":"string","minLength":1,"maxLength":120},"prompt":{"type":"string","minLength":1,"maxLength":10000},"options":{"anyOf":[{"$ref":"#/components/schemas/StudioImageOptions"},{"$ref":"#/components/schemas/StudioVideoOptions"},{"$ref":"#/components/schemas/StudioAudioOptions"}]}},"required":["mode","prompt"]},"StudioImageOptions":{"type":"object","properties":{"aspectRatio":{"type":"string","enum":["1:1","16:9","9:16","4:3","3:4"]},"negativePrompt":{"type":"string","maxLength":2000},"referenceImage":{"type":"string","format":"uri"},"referenceImages":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":8},"referenceMode":{"type":"string","enum":["style","structure","character"]},"referenceStrength":{"type":"number","minimum":0,"maximum":1},"quality":{"type":"string","enum":["low","medium","high","auto"]},"background":{"type":"string","enum":["auto","transparent","opaque"]},"thinkingLevel":{"type":"string","enum":["very low","low","medium","high"]}}},"StudioVideoOptions":{"type":"object","properties":{"aspectRatio":{"type":"string","enum":["1:1","16:9","9:16","4:3","3:4"]},"duration":{"type":"integer","minimum":1,"maximum":60},"resolution":{"type":"string","enum":["480p","720p","1080p"]},"generateAudio":{"type":"boolean"},"negativePrompt":{"type":"string","maxLength":2000},"firstFrame":{"type":"string","format":"uri"},"firstFrameVideo":{"type":"string","format":"uri"},"referenceImages":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":9},"referenceVideos":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":3},"lastFrame":{"type":"string","format":"uri"},"camera":{"type":"string","maxLength":120},"keepOriginalSound":{"type":"boolean"},"characterOrientation":{"type":"string","enum":["image","video"]},"waitForCompletion":{"type":"boolean"}}},"StudioAudioOptions":{"type":"object","properties":{"lyrics":{"type":"string","maxLength":3500},"instrumental":{"type":"boolean"},"voice":{"type":"string","maxLength":120},"referenceAudios":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":3},"referenceImage":{"type":"string","format":"uri"},"outputFormat":{"type":"string","enum":["mp3","wav","pcm","ogg_opus"]},"sampleRate":{"anyOf":[{"type":"number","enum":[8000]},{"type":"number","enum":[16000]},{"type":"number","enum":[24000]},{"type":"number","enum":[32000]},{"type":"number","enum":[44100]},{"type":"number","enum":[48000]}]},"speed":{"type":"number","minimum":0.5,"maximum":2},"volume":{"type":"number","minimum":0.5,"maximum":2},"pitch":{"type":"integer","minimum":-12,"maximum":12}}},"SeedanceGenerateRequest":{"type":"object","properties":{"mode":{"type":"string","enum":["video","image-single","image-storyboard","image-character-sheet"]},"segments":{"type":"array","items":{"type":"object","additionalProperties":{}},"description":"Ordered prompt segments. Each is `{kind:'text',text}` or `{kind:'mention',mention:{...}}`. See SeedDance docs for the mention shape."},"settings":{"type":"object","additionalProperties":{},"description":"Mode-specific settings (video: model/aspectRatio/duration/resolution/generateAudio; image: aspectRatio/size/count)."},"templateId":{"type":["string","null"],"format":"uuid"},"template":{"type":"object","additionalProperties":{}}},"required":["mode","segments","settings"]},"SeedancePromptOptimizeRequest":{"type":"object","properties":{"segments":{"type":"array","items":{"type":"object","additionalProperties":{}}},"mode":{"type":"string","enum":["video","image-single","image-storyboard","image-character-sheet"]},"settings":{"type":"object","additionalProperties":{}}},"required":["segments"]},"VoiceEnhanceRequest":{"type":"object","properties":{"voiceId":{"type":"string","minLength":1}},"required":["voiceId"]},"DubRequest":{"type":"object","properties":{"targetLang":{"type":"string","minLength":1,"description":"ISO 639-1 code, e.g. es, fr, de, pt, ja, zh."}},"required":["targetLang"]},"UpscaleClipRequest":{"type":"object","properties":{"r2Key":{"type":"string","minLength":1,"description":"Key from createAssetUpload/importAssetFromUrl (api-uploads/… or api-imports/…)."}},"required":["r2Key"]},"VoiceEnhanceClipRequest":{"type":"object","properties":{"r2Key":{"type":"string","minLength":1,"description":"Key from createAssetUpload/importAssetFromUrl (api-uploads/… or api-imports/…)."},"voiceId":{"type":"string","minLength":1}},"required":["r2Key","voiceId"]},"AiEditUploadRequest":{"type":"object","properties":{"fileName":{"type":"string","minLength":1,"maxLength":255},"fileType":{"type":"string","enum":["video/mp4","video/webm","video/quicktime","video/x-matroska"]},"fileSize":{"type":"integer","exclusiveMinimum":0}},"required":["fileName","fileType","fileSize"]},"CreateAiEditRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"source":{"type":"object","properties":{"r2Key":{"type":"string","description":"From ai-edit/uploads; must start with uploads/ai-edit/{userId}/."},"fileName":{"type":"string","minLength":1,"maxLength":255},"fileSize":{"type":"integer","exclusiveMinimum":0},"contentType":{"type":"string"},"durationSeconds":{"type":"number","exclusiveMinimum":0,"maximum":36000}},"required":["r2Key","fileName","durationSeconds"]},"recipe":{"type":"string","enum":["captions-only","polished-broll"]},"preferences":{"type":"object","properties":{"recipe":{"type":"string","enum":["captions-only","polished-broll"]},"editStyle":{"type":"string","enum":["bloom","prism","slam","lava","editorial","parallax","matrix","highlight","clipwipe"]},"texturePreset":{"type":"string","enum":["lava","marble","metal","candy","rock","wood"]},"accentColor":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"broll":{"type":"boolean"},"captionStyle":{"type":"string","enum":["classic","bold","minimal","neon","podcast","meme","karaoke"]},"captionPosition":{"type":"string","enum":["auto","bottom","center","top"]},"sfxIntensity":{"type":"string","enum":["off","subtle","punchy"]},"outputFormat":{"type":"string","enum":["9:16","1:1","16:9"]},"notes":{"type":"string","maxLength":1000}},"required":["recipe","captionStyle","captionPosition","sfxIntensity","outputFormat"]}},"required":["source","recipe","preferences"]},"CharacterSwapUploadRequest":{"type":"object","properties":{"kind":{"type":"string","enum":["character-image","driving-video"]},"fileName":{"type":"string","minLength":1,"maxLength":255},"fileType":{"type":"string","minLength":1,"maxLength":100},"fileSize":{"type":"integer","exclusiveMinimum":0}},"required":["kind","fileName","fileType","fileSize"]},"CharacterSwapImportRequest":{"type":"object","properties":{"characterId":{"type":"string","minLength":1,"maxLength":200},"imageUrl":{"type":"string","maxLength":2000,"format":"uri"},"influencerAssetId":{"type":"string","format":"uuid"},"fileName":{"type":"string","minLength":1,"maxLength":255}}},"CreateCharacterSwapRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"character":{"type":"object","properties":{"r2Key":{"type":"string"},"fileName":{"type":"string","minLength":1,"maxLength":255},"fileSize":{"type":"integer","exclusiveMinimum":0},"contentType":{"type":"string"}},"required":["r2Key","fileName"]},"drivingVideo":{"type":"object","properties":{"r2Key":{"type":"string"},"fileName":{"type":"string","minLength":1,"maxLength":255},"fileSize":{"type":"integer","exclusiveMinimum":0},"contentType":{"type":"string"},"durationSeconds":{"type":"number","exclusiveMinimum":0,"maximum":120}},"required":["r2Key","fileName","durationSeconds"]},"prompt":{"type":"string","maxLength":2000},"sceneMatch":{"type":"boolean"},"resolution":{"type":"string","enum":["720p","1080p"]},"engine":{"type":"string","enum":["standard","pro"],"description":"Visual engine. \"standard\" (default): any length up to 2 minutes. \"pro\": higher movement accuracy with lipsync, +2 credits; every swapped section (video minus keep-original ranges) must be 14 s or shorter, otherwise 400 with longestSectionSeconds."},"targetFps":{"type":"string","enum":["24","48","original"]},"saveAudio":{"type":"boolean"},"ignoreAudio":{"type":"boolean"},"turbo":{"type":"boolean"},"voiceChange":{"type":"object","properties":{"enabled":{"type":"boolean"},"voiceId":{"type":"string","minLength":1},"voiceName":{"type":"string","maxLength":120}},"required":["enabled"]},"keepOriginalVisualRanges":{"type":"array","items":{"type":"object","properties":{"startMs":{"type":"number","minimum":0,"description":"Inclusive start time in milliseconds for footage that should keep its original visuals."},"endMs":{"type":"number","exclusiveMinimum":0,"description":"End time in milliseconds. Each range must be at least 250 ms long."}},"required":["startMs","endMs"]},"maxItems":20,"description":"Up to 20 source-video ranges to splice back over the swapped result. Character Swap applies everywhere else; audio processing is unchanged."}},"required":["character","drivingVideo"]},"ImportAssetRequest":{"type":"object","properties":{"url":{"type":"string","maxLength":2000,"format":"uri"},"filename":{"type":"string","maxLength":255}},"required":["url"]},"CreateAssetUploadRequest":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":255},"contentType":{"type":"string","maxLength":100,"pattern":"^(image|video)\\/"}},"required":["filename","contentType"]},"CreateCharacterRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"fromLibraryId":{"type":"string","maxLength":200},"imageUrl":{"type":"string","maxLength":2000,"format":"uri"},"prompt":{"type":"string","minLength":5,"maxLength":2000},"defaultVoiceId":{"type":"string","maxLength":200}}},"CreateInfluencerRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","maxLength":2000},"tenantBrandId":{"type":["string","null"],"format":"uuid"},"persona":{"type":["string","null"],"maxLength":2000},"visualIdentity":{"type":["string","null"],"maxLength":2000},"voiceId":{"type":["string","null"],"maxLength":100},"metadata":{"type":"object","additionalProperties":{}}},"required":["name"]},"UpdateInfluencerRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","maxLength":2000},"tenantBrandId":{"type":["string","null"],"format":"uuid"},"persona":{"type":["string","null"],"maxLength":2000},"visualIdentity":{"type":["string","null"],"maxLength":2000},"voiceId":{"type":["string","null"],"maxLength":100},"status":{"type":"string","enum":["draft","building","ready","failed","archived"]},"metadata":{"type":"object","additionalProperties":{}}}},"CreateInfluencerAssetRequest":{"type":"object","properties":{"kind":{"type":"string","enum":["visual","audio","text","reference","driving-source","intermediate"]},"subkind":{"type":"string","minLength":1,"maxLength":50},"role":{"type":"string","minLength":1,"maxLength":80},"url":{"type":"string","maxLength":1000,"format":"uri"},"r2Key":{"type":["string","null"],"minLength":1,"maxLength":1000},"thumbnailUrl":{"type":["string","null"],"maxLength":1000,"format":"uri"},"durationMs":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":120000},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":80},"maxItems":50},"qualityScore":{"type":["number","null"],"minimum":0,"maximum":100},"metadata":{"type":"object","additionalProperties":{}}},"required":["kind","subkind","role","url"]},"CreateInfluencerBuildRequest":{"type":"object","properties":{"referenceAssetId":{"type":"string","format":"uuid"},"seedImageAssetId":{"type":"string","format":"uuid"},"seedImageAssetIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":4},"drivingAssetIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":10},"brollCount":{"type":"integer","minimum":0,"maximum":5},"generateReferenceSheet":{"type":"boolean"},"staticSceneCount":{"type":"integer","minimum":0,"maximum":5},"facelessBrollCount":{"type":"integer","minimum":0,"maximum":10},"prompt":{"type":"string","maxLength":1000},"resolution":{"type":"string","enum":["720p","1080p"]},"targetFps":{"type":"string","enum":["24","48","original"]},"saveAudio":{"type":"boolean"},"turbo":{"type":"boolean"},"starterBundle":{"type":"boolean"}}},"GenerateInfluencerLookRequest":{"type":"object","properties":{"prompt":{"type":"string","maxLength":500},"seedImageAssetId":{"type":"string","format":"uuid"},"seedImageAssetIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":4}}},"CreateInfluencerSnackRequest":{"type":"object","properties":{"prompt":{"type":"string","maxLength":2000},"context":{"type":"string","maxLength":2000},"types":{"type":"array","items":{"type":"string","enum":["slides","text-wall","ai-ugc","broll-demo","greenscreen-meme","meme-edit","single-image","sticker-pack","static-ad","ugc-ad","animated-ad","greenscreen-ad","music-ad"]},"minItems":1,"maxItems":13},"count":{"type":"integer","minimum":1,"maximum":5},"exclude":{"type":"array","items":{"type":"string","enum":["slides","text-wall","ai-ugc","broll-demo","greenscreen-meme","meme-edit","single-image","sticker-pack","static-ad","ugc-ad","animated-ad","greenscreen-ad","music-ad"]},"maxItems":13}}},"UpdateInfluencerAgentRequest":{"type":"object","properties":{"instructions":{"type":"string","maxLength":2000},"voice":{"type":"string","maxLength":600},"audience":{"type":"string","maxLength":600},"doDont":{"type":"string","maxLength":800},"brandFacts":{"type":"string","maxLength":1200},"managedAccountIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":20},"socialBrandId":{"type":["string","null"],"format":"uuid"},"socialAccountIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":11}}},"DecideInfluencerDraftsRequest":{"type":"object","properties":{"draftIds":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":20},"decision":{"type":"string","enum":["approve","reject","request_changes"]},"reason":{"type":"string","maxLength":2000},"scheduledAt":{"type":"string","format":"date-time"}},"required":["draftIds","decision"]},"UpdateInfluencerKnowledgeRequest":{"type":"object","properties":{"instructions":{"type":"string","maxLength":2000},"voice":{"type":"string","maxLength":600},"audience":{"type":"string","maxLength":600},"do_dont":{"type":"string","maxLength":800},"brand_facts":{"type":"string","maxLength":1200}}},"SendInfluencerMessageRequest":{"type":"object","properties":{"body":{"type":"string","minLength":1,"maxLength":8000}},"required":["body"]},"ChatWithInfluencerRequest":{"type":"object","properties":{"message":{"type":"string","minLength":1,"maxLength":8000}},"required":["message"]},"GenerateInfluencerStudioImageRequest":{"type":"object","properties":{"prompt":{"type":"string","minLength":3,"maxLength":10000},"aspectRatio":{"type":"string","enum":["1:1","16:9","9:16","4:3","3:4"]},"referenceImages":{"type":"array","items":{"type":"string","minLength":1},"maxItems":4}},"required":["prompt"]},"CreateSocialBrandRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":50},"description":{"type":"string","minLength":1,"maxLength":500},"industry":{"type":"string","minLength":1,"maxLength":50},"language":{"type":"string"},"targetAudience":{"type":"string","maxLength":500},"marketingStrategy":{"type":"string","maxLength":4000},"websiteUrl":{"type":"string","maxLength":500,"format":"uri"},"avatarUrl":{"type":"string","maxLength":500,"format":"uri"},"demoVideoUrl":{"type":"string","maxLength":1000,"format":"uri"}},"required":["name","description","industry"]},"CreateSocialPostRequest":{"type":"object","properties":{"brandId":{"type":"string","format":"uuid"},"accountIds":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":11},"assetKind":{"type":"string","enum":["video","photo","carousel"]},"videoUrl":{"type":"string","format":"uri"},"photoUrls":{"type":"array","items":{"type":"string","format":"uri"},"minItems":1,"maxItems":20},"caption":{"type":"string","maxLength":5000},"title":{"type":"string","maxLength":200},"thumbnailUrl":{"type":"string","format":"uri"},"tags":{"type":"array","items":{"type":"string","maxLength":60},"maxItems":30},"visibility":{"type":"string","enum":["public","unlisted","private"]},"platformOverrides":{"type":"object","additionalProperties":{}},"scheduledAt":{"type":"string","format":"date-time"},"addToQueue":{"type":"boolean"}},"required":["brandId","accountIds","assetKind"]},"ManagedAccount":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["awaiting_setup","awaiting_provisioning","provisioning","warming_up","active","action_needed","paused","cancelled","reserved"],"description":"`reserved`: ended, but can be reactivated until `reservedUntil`."},"statusLabel":{"type":"string"},"sandbox":{"type":"boolean","description":"Simulated: no charges, goes live and publishes within minutes."},"needsSetup":{"type":"boolean"},"queueable":{"type":"boolean","description":"Can take a queued post now."},"postable":{"type":"boolean"},"platform":{"type":["string","null"],"enum":["tiktok","instagram",null]},"username":{"type":["string","null"]},"name":{"type":["string","null"]},"bio":{"type":["string","null"]},"pfpUrl":{"type":["string","null"]},"warming":{"type":["object","null"],"properties":{},"additionalProperties":{}},"analytics":{"type":["object","null"],"properties":{},"additionalProperties":{}},"posting":{"type":"object","properties":{"earliestQueueDate":{"type":["string","null"]},"dailyCap":{"type":"integer"},"creditsPerPost":{"type":"integer"}},"required":["earliestQueueDate","dailyCap","creditsPerPost"],"additionalProperties":{}},"cancelAt":{"type":["string","null"],"description":"Set once cancelled; the account stays live until then."},"reservedUntil":{"type":["string","null"],"description":"Cancelled with reserve: after `cancelAt` the account is kept (no posting, no billing) and can be reactivated until then. After it, the account is gone."},"createdAt":{"type":["string","null"]}},"required":["id","status","statusLabel","sandbox","needsSetup","queueable","postable","platform","username","name","bio","pfpUrl","warming","analytics","posting","cancelAt","reservedUntil","createdAt"],"additionalProperties":{}},"ManagedPost":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["scheduled","pending","posted","failed","deleted"]},"caption":{"type":["string","null"]},"sourceAssetUrl":{"type":["string","null"]},"publicPostUrl":{"type":["string","null"]},"musicLink":{"type":["string","null"]},"scheduledAt":{"type":["string","null"]},"postedAt":{"type":["string","null"]},"views":{"type":["integer","null"]},"likes":{"type":["integer","null"]},"comments":{"type":["integer","null"]},"createdAt":{"type":"string"}},"required":["id","status","caption","sourceAssetUrl","publicPostUrl","musicLink","scheduledAt","postedAt","views","likes","comments","createdAt"]},"CreateManagedAccountsRequest":{"type":"object","properties":{"quantity":{"type":"integer","minimum":1,"maximum":10,"description":"Default 1."},"sandbox":{"type":"boolean"},"reactivateAccountId":{"type":"string","format":"uuid","description":"Reactivate this account instead of creating new ones."}}},"SetupManagedAccountRequest":{"type":"object","properties":{"platform":{"type":"string","enum":["tiktok","instagram"]},"username":{"type":"string","pattern":"^[a-zA-Z0-9._]{2,24}$"},"name":{"type":"string","minLength":1},"bio":{"type":"string","maxLength":160},"searchTerms":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Niche keywords."},"pfpUrl":{"type":"string","format":"uri","description":"Public profile photo URL."},"gender":{"type":"string","enum":["male","female","faceless"]},"age":{"type":"integer"}},"required":["platform","username","name","searchTerms","pfpUrl"]},"UpdateManagedAccountRequest":{"type":"object","properties":{"username":{"type":"string"},"name":{"type":"string"},"bio":{"type":"string","maxLength":120}}},"PublishToManagedAccountRequest":{"type":"object","properties":{"caption":{"type":"string","minLength":1},"queueFor":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"YYYY-MM-DD (UTC)."},"sourceProjectId":{"type":"string","format":"uuid"},"videoUrl":{"type":"string","format":"uri"},"imageUrls":{"type":"array","items":{"type":"string","format":"uri"}},"musicLink":{"type":"string","description":"TikTok sound link, or Instagram audio link / song name."},"idempotencyKey":{"type":"string","description":"Makes retries safe."}},"required":["caption"]}},"parameters":{}},"paths":{"/api/v1/jobs/{id}":{"get":{"tags":["Jobs"],"operationId":"getApiJob","summary":"Poll a job","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","example":"85d535ac-219e-4fde-b527-488ed1157bb2"},"required":true,"name":"id","in":"path","description":"The public API job ID."}],"responses":{"200":{"description":"Job state and result payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetApiJobResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Job not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/credits":{"get":{"tags":["Credits"],"operationId":"getCredits","summary":"Get credit balance and recent transactions","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"integer","example":10},"required":false,"name":"limit","in":"query","description":"Maximum number of recent transactions to return."}],"responses":{"200":{"description":"Current balance and credit history.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditsResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/credits/topup":{"get":{"tags":["Credits"],"operationId":"listCreditTopupOffers","summary":"List machine-payment credit top-up offers","description":"Fixed top-up sizes with USD prices and the URL to POST for each, plus which payment rails this deployment accepts. Pass `required` (credits a blocked action needs) to get the smallest size that covers it.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1},"required":false,"name":"required","in":"query"},{"schema":{"type":["integer","null"],"minimum":0},"required":false,"name":"balance","in":"query"}],"responses":{"200":{"description":"Offers and rails.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditsTopupOffersResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/snacks":{"post":{"tags":["Snacks"],"operationId":"createSnack","summary":"Create a snack pack","description":"Async — kicks off a snack generation job for a brand. Returns a jobId immediately. Optionally renders the snacks server-side when `render: true` (+3 credits, URLs in `result.renderedAssets[]`).","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSnackRequest"}}}},"responses":{"201":{"description":"Snack job accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSnackResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Insufficient credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Brand not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Failed to dispatch the worker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"tags":["Snacks"],"operationId":"listSnacks","summary":"List generated snacks","description":"Returns the partner's snack posts, optionally filtered by `brandId`. Each entry includes the full manifest.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"brandId","in":"query","description":"Filter by tenant brand UUID."},{"schema":{"type":"integer","example":20},"required":false,"name":"limit","in":"query","description":"Max items (default 20, max 100)."},{"schema":{"type":"integer","example":0},"required":false,"name":"offset","in":"query","description":"Pagination offset."}],"responses":{"200":{"description":"List of snack posts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SnacksListResponse"}}}},"400":{"description":"Invalid query.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/snacks/on-demand":{"post":{"tags":["Snacks"],"operationId":"createOnDemandSnacks","summary":"Ads on demand","description":"Async. Make ads from a store, service or app URL, then poll GET /api/v1/jobs/{id}. Pro and Scale plans. Ad types and pricing: [Ads on Demand](/docs/ads-on-demand).","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOnDemandSnackRequest"}}}},"responses":{"201":{"description":"Ad job accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOnDemandSnackResponse"}}}},"400":{"description":"Invalid request or unreadable page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Insufficient credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Plan doesn't include ads on demand.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Couldn't read the page or start the job.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/snacks/memes":{"post":{"tags":["Snacks"],"operationId":"createMeme","summary":"Generate memes","description":"Async, prompt-first meme generation. Rendering is included. Requests 1–5 variations of one type and returns a jobId immediately; poll GET /api/v1/jobs/{id}. Brand context is optional.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMemeRequest"}}}},"responses":{"201":{"description":"Meme job accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMemeResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Insufficient credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Brand not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Failed to dispatch the worker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/snacks/{id}":{"get":{"tags":["Snacks"],"operationId":"getSnack","summary":"Fetch a snack post","description":"Returns the manifest and metadata for a single snack post owned by the partner.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","example":"75d0431f-7259-48a8-a2e8-242ade5625da"},"required":true,"name":"id","in":"path","description":"The snack post UUID."}],"responses":{"200":{"description":"Snack post.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SnackPost"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Snack not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/snacks/brands":{"post":{"tags":["Snacks Brands"],"operationId":"createSnackBrand","summary":"Create a brand for snack generation","description":"Persists a brand belonging to one of the partner's end-customers. The returned `id` is used as `brandId` on POST /api/v1/snacks. If `targetAudience` is omitted we derive one from the description + industry.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSnackBrandRequest"}}}},"responses":{"201":{"description":"Brand created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SnackBrand"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"tags":["Snacks Brands"],"operationId":"listSnackBrands","summary":"List brands","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"integer","example":50},"required":false,"name":"limit","in":"query","description":"Max items (default 50, max 200)."},{"schema":{"type":"integer","example":0},"required":false,"name":"offset","in":"query","description":"Pagination offset."}],"responses":{"200":{"description":"Paginated list of brands.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SnackBrandsListResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/snacks/brands/{id}":{"get":{"tags":["Snacks Brands"],"operationId":"getSnackBrand","summary":"Get a brand","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","example":"ef7eff3e-e1d3-4ff2-b2d0-d5d274b460ee"},"required":true,"name":"id","in":"path","description":"The tenant brand UUID."}],"responses":{"200":{"description":"Brand.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SnackBrand"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Brand not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Snacks Brands"],"operationId":"updateSnackBrand","summary":"Update a brand","description":"All fields optional. Pass `null` on `websiteUrl`/`logoUrl` to clear them.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","example":"ef7eff3e-e1d3-4ff2-b2d0-d5d274b460ee"},"required":true,"name":"id","in":"path","description":"The tenant brand UUID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSnackBrandRequest"}}}},"responses":{"200":{"description":"Brand updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SnackBrand"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Brand not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Snacks Brands"],"operationId":"deleteSnackBrand","summary":"Delete a brand","description":"Existing snack posts referencing this brand are preserved — their `brandId` is set to `null`.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","example":"ef7eff3e-e1d3-4ff2-b2d0-d5d274b460ee"},"required":true,"name":"id","in":"path","description":"The tenant brand UUID."}],"responses":{"204":{"description":"Brand deleted."},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Brand not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/managed-accounts":{"get":{"tags":["Managed Accounts"],"operationId":"listManagedAccounts","summary":"List your managed accounts","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Managed accounts.","content":{"application/json":{"schema":{"type":"object","properties":{"accounts":{"type":"array","items":{"$ref":"#/components/schemas/ManagedAccount"}}},"required":["accounts"]}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Managed Accounts"],"operationId":"createManagedAccounts","summary":"Create managed accounts","description":"Scale plan. Charges the card on file the full monthly price per account today. Accounts bought in one request renew together, monthly from the purchase date; accounts bought later have their own renewal date. There is no proration. `sandbox: true` creates free simulated accounts instead (up to 10). New accounts start in `awaiting_setup`.\n\n`reactivateAccountId` brings back one of your accounts instead of creating one. A `reserved` account returns as the same account (username, followers, posts) on a new monthly subscription charged from today. An account whose `cancelAt` hasn't passed yet simply carries on, with no charge. An account past its reserve can't be reactivated (410).","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","maxLength":200,"description":"Same key and body returns the original response. A different body returns 409. Failed requests are not stored, so the key can be retried."},"required":false,"description":"Same key and body returns the original response. A different body returns 409. Failed requests are not stored, so the key can be retried.","name":"Idempotency-Key","in":"header"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateManagedAccountsRequest"}}}},"responses":{"200":{"description":"Cancellation withdrawn (reactivation before `cancelAt`).","content":{"application/json":{"schema":{"type":"object","properties":{"accounts":{"type":"array","items":{"$ref":"#/components/schemas/ManagedAccount"}}},"required":["accounts"]}}}},"201":{"description":"Created, or reactivated from reserve.","content":{"application/json":{"schema":{"type":"object","properties":{"accounts":{"type":"array","items":{"$ref":"#/components/schemas/ManagedAccount"}}},"required":["accounts"]}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"No card on file, or the payment failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Requires the Scale plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Account limit reached, Idempotency-Key reused with a different body, still in progress, account not cancelled, or account can no longer be reactivated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"The account is past its reserve and can't be reactivated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Another purchase is in progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/managed-accounts/{id}/setup":{"post":{"tags":["Managed Accounts"],"operationId":"setupManagedAccount","summary":"Set up a managed account","description":"Only for accounts in `awaiting_setup`. The account then moves to `provisioning`.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path","description":"Managed account UUID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetupManagedAccountRequest"}}}},"responses":{"200":{"description":"Saved.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"account":{"$ref":"#/components/schemas/ManagedAccount"}},"required":["ok","account"]}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Setup already complete.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/managed-accounts/{id}":{"get":{"tags":["Managed Accounts"],"operationId":"getManagedAccount","summary":"Get one managed account","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path","description":"Managed account UUID."}],"responses":{"200":{"description":"Managed account.","content":{"application/json":{"schema":{"type":"object","properties":{"account":{"$ref":"#/components/schemas/ManagedAccount"}},"required":["account"]}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Managed Accounts"],"operationId":"updateManagedAccount","summary":"Edit a managed account profile","description":"Active accounts only. Username: 30-day cooldown; name: 7-day cooldown; bio: 80 chars on TikTok, 120 on Instagram. Applied asynchronously (`pending: true`).","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path","description":"Managed account UUID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateManagedAccountRequest"}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Cooldown active or not ready.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Service unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Managed Accounts"],"operationId":"deleteManagedAccount","summary":"Cancel a managed account","description":"Live accounts: billing stops at the end of the current period (no proration). The account keeps working until `cancelAt`, then is removed. Sandbox accounts are removed immediately.\n\n`reserve=true` (Scale): charges 250 credits now and keeps the account on reserve for 14 days after `cancelAt` instead of removing it: status `reserved`, no posting, no billing. Reactivate it with `POST /api/managed-accounts` and `reactivateAccountId`; after `reservedUntil` it is gone. Can be sent again to add reserve to a scheduled cancellation. In the sandbox the account ends 2 minutes later and stays reserved for 10 minutes, at no cost.\n\nOn a `reserved` account, DELETE gives up the reserve and removes it now.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path","description":"Managed account UUID."},{"schema":{"type":"string","enum":["true","false"],"description":"Keep the account on reserve after it ends (250 credits, charged now)."},"required":false,"description":"Keep the account on reserve after it ends (250 credits, charged now).","name":"reserve","in":"query"}],"responses":{"200":{"description":"Cancelled.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"deleted":{"type":"boolean"},"cancelAt":{"type":"string"},"reservedUntil":{"type":["string","null"]},"reserveCredits":{"type":"integer","description":"Credits charged by this call for the reserve (0 on a repeat)."}},"required":["ok","deleted"]}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Not enough credits for the reserve.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Reserve requires the Scale plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Can't be cancelled by API — contact support — or this account can't be kept on reserve.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/managed-accounts/{id}/capacity":{"get":{"tags":["Managed Accounts"],"operationId":"getManagedAccountCapacity","summary":"Which days a managed account can take a post","description":"Earliest bookable day, daily cap, credits per post and booked counts for the next 60 days.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path","description":"Managed account UUID."}],"responses":{"200":{"description":"Capacity.","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/managed-accounts/pulse":{"get":{"tags":["Managed Accounts"],"operationId":"getManagedAccountsPulse","summary":"Performance across all your managed accounts","description":"Totals, deltas, daily series, top posts and a per-account leaderboard. Refreshed about daily.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"integer"},"required":false,"name":"days","in":"query","description":"7, 14, 30 (default) or 90."},{"schema":{"type":"string","enum":["tiktok","instagram"]},"required":false,"name":"platform","in":"query","description":"Omit for all."}],"responses":{"200":{"description":"Pulse.","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"400":{"description":"Invalid days.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/managed-accounts/{id}/posts":{"get":{"tags":["Managed Accounts"],"operationId":"listManagedPosts","summary":"List a managed account's posts","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path","description":"Managed account UUID."}],"responses":{"200":{"description":"Posts.","content":{"application/json":{"schema":{"type":"object","properties":{"posts":{"type":"array","items":{"$ref":"#/components/schemas/ManagedPost"}}},"required":["posts"]}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Managed Accounts"],"operationId":"publishToManagedAccount","summary":"Queue a post on a managed account","description":"Posts are booked for a day (`queueFor`, default the earliest open day) and go live that day or the next. At least a day's notice, 2 posts per account per day, charged per post. Check capacity first.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path","description":"Managed account UUID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishToManagedAccountRequest"}}}},"responses":{"200":{"description":"Queued.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"post":{"$ref":"#/components/schemas/ManagedPost"}},"required":["ok","post"]}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Not enough credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Account not ready or day full.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Service unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/managed-accounts/{id}/posts/{postId}":{"delete":{"tags":["Managed Accounts"],"operationId":"deleteManagedPost","summary":"Delete a scheduled managed post","description":"Queued posts can't be withdrawn once submitted (409).","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path","description":"Managed account UUID."},{"schema":{"type":"string"},"required":true,"name":"postId","in":"path","description":"Managed post UUID."}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Can't be withdrawn.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Service unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"webhooks":{}}